Pular para o conteúdo principal

InternalContextualHero

Componente de destaque utilizado para exibir mensagens personalizadas baseadas na jornada do usuário. Permite combinar título, descrição, lista de itens, botões de ação e uma imagem opcional. Suporta diferentes variantes visuais (type) e posições de imagem (imagePosition).

Importação​

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

Importação de tipos TypeScript​

import type {
  InternalContextualHeroProps,
  InternalContextualHeroListItemString,
  InternalContextualHeroAction,
} from '@useblu/ocean-react';

Playground Interativo​

Explore o componente InternalContextualHero 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 InternalContextualHero.

No Storybook você encontrará:

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

Variantes de Tipo (type)​

O componente suporta três variantes visuais que alteram as cores dos botões e o estilo geral:

Default​

Estilo padrão com cores primárias:

🚀 Abrir no Storybook

Warning​

Estilo de aviso com cores de alerta:

🚀 Abrir no Storybook

Negative​

Estilo crítico/negativo para erros:

🚀 Abrir no Storybook

Posição da Imagem (imagePosition)​

O componente permite controlar a posição vertical da imagem na lateral direita:

Top (padrão)​

Imagem alinhada ao topo:

🚀 Abrir no Storybook

Bottom​

Imagem alinhada à parte inferior:

🚀 Abrir no Storybook

Full​

Imagem ocupa toda a altura:

🚀 Abrir no Storybook

Exemplos de Uso​

Todas as variantes​

Hero com todas as variantes de tipo e posição:

🚀 Abrir no Storybook

Com uma ação​

Hero com apenas um botão de ação:

🚀 Abrir no Storybook

Sem ações​

Hero sem botões de ação:

🚀 Abrir no Storybook

Sem imagem​

Hero sem a seção de imagem:

🚀 Abrir no Storybook

Com ListAction​

Hero utilizando componentes ListAction como itens da lista:

🚀 Abrir no Storybook

Lista de texto com ícones​

Hero com itens de texto simples e ícones:

🚀 Abrir no Storybook

Lista de texto sem ícones​

Hero com itens de texto simples sem ícones:

🚀 Abrir no Storybook

Mínimo​

Hero apenas com as propriedades obrigatórias:

🚀 Abrir no Storybook

API​

Props​

PropTipoPadrãoDescrição
type'default' | 'warning' | 'negative''default'Define a variante visual do hero. Altera as cores dos botões de ação.
titlestring-Obrigatório. Título principal exibido no cabeçalho do hero.
descriptionstring-Obrigatório. Descrição exibida abaixo do título.
listItems(ReactNode | InternalContextualHeroListItemString)[]-Obrigatório. Lista de itens a serem exibidos no corpo do hero.
imagestring | ReactNode-Imagem ou componente a ser exibido na lateral direita. Se for string, renderiza como <img>.
imagePosition'top' | 'bottom' | 'full''top'Posição da imagem em relação ao conteúdo.
actions[InternalContextualHeroAction] | [InternalContextualHeroAction, InternalContextualHeroAction]-Botões de ação (máximo 2). As variantes são baseadas no type do hero.
classNamestring-Classes CSS adicionais para o elemento raiz.

Tipos​

InternalContextualHeroListItemString​

type InternalContextualHeroListItemString = {
  /** Icon element to be displayed before the description. */
  icon?: ReactNode;
  /** Text content of the list item. */
  description: string;
};

InternalContextualHeroAction​

type InternalContextualHeroAction = {
  /** Text displayed on the action button. */
  label: string;
  /** Callback function triggered when the action button is clicked. */
  onClick: () => void;
};

Variantes de botões por type​

Os botões de ação adaptam suas cores automaticamente com base no type do hero:

typeBotão primárioBotão secundário
defaultprimarytertiary
warningprimaryWarningtertiaryWarning
negativeprimaryCriticaltertiaryCritical

Estrutura de listItems​

O prop listItems aceita dois tipos de itens:

1. Objeto com descrição (e ícone opcional)​

listItems={[
  { icon: <CheckCircleOutline size={20} />, description: 'Item com ícone' },
  { description: 'Item sem ícone' },
]}

2. ReactNode customizado​

listItems={[
  <ListAction key="1" title="Item 1" description="Descrição" type="text" />,
  <CustomComponent key="2" />,
]}

Acessibilidade​

  • ✅ Utiliza elementos semânticos HTML
  • ✅ Botões de ação são elementos <button> nativos
  • ✅ Imagem inclui atributo alt automaticamente (usando o título)
  • ✅ Suporte a navegação por teclado
  • ✅ Suporte a ref forwarding

Boas práticas​

  • Use títulos claros e concisos
  • A descrição deve complementar o título, não repeti-lo
  • Limite a lista a 3-5 itens para melhor legibilidade
  • Use no máximo 2 botões de ação para evitar sobrecarga visual
  • A imagem deve ser relevante ao contexto do hero
  • Use type="warning" para mensagens de atenção e type="negative" para erros ou ações críticas
  • Escolha o imagePosition apropriado para o layout: top para imagens pequenas, full para imagens que precisam de mais destaque