CardGroup

O CardGroup é um componente usado para agrupar informações relacionadas em um layout organizado. Ele suporta diferentes variantes (minimal e header) e pode incluir título, subtítulo, contador, tag de destaque e uma ação clicável com contador opcional.

Importação

import { CardGroup } from '@useblu/ocean-react';

Importação específica (recomendado para tree-shaking)

import { CardGroup } from '@useblu/ocean-react/CardGroup';

Importação de tipos TypeScript

import type { ICardGroupProps, TagProps } from '@useblu/ocean-react';

// Uso em componente customizado
const MyComponent: React.FC<ICardGroupProps> = (props) => {
  return <CardGroup {...props} />;
};

// Exemplo com tag
const CardWithTag: React.FC = () => {
  const tag: TagProps = {
    children: 'Novo',
    variant: 'highlight',
    type: 'positive',
  };

  return (
    <CardGroup
      title="Título"
      subtitle="Subtítulo"
      tag={tag}
      actionLabel="Ver mais"
      actionCount={5}
    />
  );
};

Playground Interativo

Explore o componente CardGroup no playground interativo do Storybook:

🚀 Abrir no Storybook

Documentação Completa

Para documentação técnica detalhada, exemplos de uso e API completa, consulte o Storybook do CardGroup.

No Storybook você encontrará:

• ✅ Controles interativos para testar todas as props
• ✅ API gerada automaticamente com tipagem completa
• ✅ Exemplos visuais de todas as variantes
• ✅ Playground para experimentação rápida

Uso básico

Card minimal com conteúdo

<CardGroup
  title="Meu Card"
  subtitle="Descrição do card"
  count={5}
  actionLabel="Ver mais"
>
  <div style={{ padding: '16px' }}>
    <p>Conteúdo do card</p>
  </div>
</CardGroup>

Card header (apenas cabeçalho)

<CardGroup
  title="Estatísticas"
  subtitle="Resumo dos dados"
  count={25}
  variant="header"
/>

Card com tag de destaque

<CardGroup
  title="Boletos"
  subtitle="Disponíveis para pagamento"
  tag={{
    children: 'Novo',
    variant: 'highlight',
    type: 'positive',
  }}
  actionLabel="Ver boletos"
  actionCount={3}
>
  <div style={{ padding: '16px' }}>
    <p>Você tem 3 boletos disponíveis para pagamento</p>
  </div>
</CardGroup>

Card com contador na ação

<CardGroup
  title="Notificações"
  subtitle="Mensagens não lidas"
  count={15}
  actionLabel="Ver todas"
  actionCount={5}
>
  <div style={{ padding: '16px' }}>
    <p>5 notificações importantes aguardando sua atenção</p>
  </div>
</CardGroup>

Cartões com fundo e estados

Card com fundo azul e tag

Quando o card precisa chamar atenção com uma cor de fundo suave e uma tag, use esta variante. Ela combina a tag com o fundo azul e o ícone de destaque para reforçar o status.

🚀 Abrir no Storybook

Card sem tag

Use quando o conteúdo deve ser acompanhado apenas por um alerta e ação, sem destacar o status via tag.

🚀 Abrir no Storybook

Card com fundo, sem alerta adicional

Para mostrar contexto com fundo azul claro, mas sem o bloco de alerta inferior, essa versão mantém o visual limpo.

🚀 Abrir no Storybook

Card sem background extra

Use este estado quando o conteúdo precisa do visual padrão, sem cor de fundo nem alertas visuais.

🚀 Abrir no Storybook

Variantes

O CardGroup oferece duas variantes principais:

Minimal (padrão)

A variante minimal exibe o conteúdo principal e a ação (se fornecida):

🚀 Abrir no Storybook

Header

A variante header exibe apenas o cabeçalho (título e subtítulo) e o contador, sem conteúdo adicional ou ação.

Exemplo com conteúdo personalizado

O CardGroup aceita qualquer conteúdo React como children:

🚀 Abrir no Storybook

Contador opcional

O contador é exibido quando a prop count é fornecida:

🚀 Abrir no Storybook

Ações interativas

Cards podem incluir botões de ação para navegação ou funcionalidades:

🚀 Abrir no Storybook

Tags de destaque

As tags permitem destacar informações importantes no cabeçalho do card. Útil para indicar status, novidades ou categorias:

🚀 Abrir no Storybook

Quando usar tags

• Status: Indicar se algo é novo, urgente ou importante
• Categorias: Classificar o tipo de conteúdo do card
• Alertas: Chamar atenção para informações que requerem ação

Configuração de tags

As tags aceitam as seguintes propriedades principais:

• children: Texto exibido na tag
• variant: Estilo visual ('highlight', 'complementary', etc.)
• type: Cor semântica ('positive', 'negative', 'warning', 'neutral')

Para mais detalhes sobre configuração de tags, consulte a documentação do componente Tag.

Contadores na ação

O botão de ação pode exibir um contador através da prop actionCount. Isso é útil para indicar:

• Número de itens não lidos ou pendentes
• Quantidade de notificações
• Total de elementos disponíveis para visualização

<CardGroup
  title="Tarefas Pendentes"
  subtitle="Projeto Alpha"
  count={8}
  actionLabel="Ver tarefas"
  actionCount={3}
>
  <div style={{ padding: '16px' }}>
    <p>3 tarefas requerem atenção imediata</p>
  </div>
</CardGroup>

Personalização do Badge da Ação

É possível customizar a cor do badge exibido no botão de ação através da prop actionBadgeColor. As cores disponíveis são brand, complementary, alert e neutral.

<CardGroup
  title="Status do Sistema"
  subtitle="Verificação de serviços"
  actionLabel="Ver detalhes"
  actionCount={3}
  actionBadgeColor="alert"
  actionClick={() => alert('Ação clicada!')}
>
  <div style={{ padding: '16px' }}>
    <p>3 serviços apresentam instabilidade.</p>
  </div>
</CardGroup>

API

Props

Prop	Tipo	Padrão	Descrição
title	string	-	O título exibido no cabeçalho
subtitle	string	-	O subtítulo exibido no cabeçalho
variant	'minimal' | 'header'	'minimal'	A variante do componente que define o layout
count	number	-	O valor exibido no contador. Se undefined, o contador fica oculto
tag	TagProps	-	Configuração da tag de destaque exibida ao lado do título
actionLabel	string	-	O texto do botão de ação
actionCount	number	-	O valor exibido no contador do botão de ação
actionClick	() => void	-	Função chamada quando o botão de ação é clicado
actionBadgeColor	'brand' | 'complementary' | 'alert' | 'neutral' | 'highlight'	-	Define a cor de fundo do badge no botão de ação
children	ReactNode	-	Conteúdo adicional exibido abaixo do cabeçalho (apenas na variante minimal)

Comportamento das variantes

• Minimal: Exibe título, subtítulo, tag, contador, conteúdo personalizado e ação (com contador opcional)
• Header: Exibe apenas título, subtítulo, tag e contador (sem conteúdo ou ação)

Classes CSS

Classe	Descrição
.ods-card-group	Estilos aplicados ao elemento raiz
.ods-card-group--minimal	Estilos aplicados quando a variante é minimal
.ods-card-group--header	Estilos aplicados quando a variante é header
.ods-card-group__header	Estilos aplicados ao container do cabeçalho
.ods-card-group__header--content	Estilos aplicados ao conteúdo interno do cabeçalho
.ods-card-group__action	Estilos aplicados ao botão de ação
.ods-card-group__action--label	Estilos aplicados ao rótulo do botão de ação

Casos de uso comuns

Dashboard com estatísticas

<div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
  <CardGroup title="Vendas" subtitle="Hoje" count={42} variant="header" />
  <CardGroup title="Usuários" subtitle="Online" count={128} variant="header" />
</div>

Lista de tarefas

<CardGroup
  title="Tarefas Pendentes"
  subtitle="Projeto Alpha"
  count={8}
  actionLabel="Ver todas"
>
  <div style={{ padding: '16px' }}>
    <ul style={{ margin: 0, paddingLeft: '20px' }}>
      <li>Revisar código</li>
      <li>Atualizar documentação</li>
      <li>Fazer deploy</li>
    </ul>
  </div>
</CardGroup>

Card de notificações

<CardGroup
  title="Notificações"
  subtitle="Últimas 24 horas"
  count={15}
  actionLabel="Marcar como lidas"
  actionCount={5}
>
  <div style={{ padding: '16px' }}>
    <p style={{ margin: 0 }}>Você tem 5 notificações urgentes não lidas.</p>
  </div>
</CardGroup>

Card com status destacado

<CardGroup
  title="Documentos"
  subtitle="Pendentes de assinatura"
  count={2}
  tag={{
    children: 'Urgente',
    variant: 'highlight',
    type: 'warning',
  }}
  actionLabel="Assinar documentos"
  actionCount={2}
>
  <div style={{ padding: '16px' }}>
    <p style={{ margin: 0 }}>2 documentos aguardando sua assinatura digital.</p>
  </div>
</CardGroup>

Card de promoção

<CardGroup
  title="Ofertas Especiais"
  subtitle="Válido até 31/12"
  tag={{
    children: 'Novo',
    variant: 'highlight',
    type: 'positive',
  }}
  actionLabel="Ver ofertas"
>
  <div style={{ padding: '16px' }}>
    <p style={{ margin: 0 }}>Confira nossas ofertas exclusivas desta semana!</p>
  </div>
</CardGroup>

Acessibilidade

• ✅ Estrutura semântica apropriada
• ✅ Navegação por teclado funcional no botão de ação
• ✅ Atributos ARIA adequados
• ✅ Suporte a screen readers

Navegação por teclado

Tecla	Função
Tab	Move o foco para o botão de ação
Enter/Space	Ativa a ação do botão

Melhores práticas

✅ Faça

• Use títulos descritivos e concisos
• Mantenha subtítulos informativos mas breves
• Use a variante header para informações resumidas
• Use a variante minimal para conteúdo mais detalhado
• Forneça ações relevantes ao contexto
• Use tags para destacar status importantes (novo, urgente, etc.)
• Adicione contadores na ação quando houver itens pendentes ou não lidos
• Use cores semânticas apropriadas nas tags (positive, negative, warning, neutral)

❌ Não faça

• Não use títulos muito longos que quebrem o layout
• Não omita subtítulos quando o contexto não for óbvio
• Não use a variante header com conteúdo complexo
• Não deixe de testar as ações dos botões
• Não sobrecarregue o card com muito conteúdo
• Não use tags desnecessárias que poluam visualmente o card
• Não abuse de contadores - use apenas quando agregar valor ao usuário

Links relacionados

• Button - Para ações isoladas
• Badge - Para indicadores numéricos
• Tag - Para tags de destaque e categorização
• Storybook - CardGroup - Documentação técnica