Contextos React e hooks

Esta página documenta os contextos React e hooks reutilizáveis do RoboStage, responsáveis por compartilhar estado, encapsular operações de dados e centralizar cálculos utilizados pela interface.

As regras de negócio compartilhadas entre diferentes funcionalidades estão documentadas em Utilitários e regras de negócio.

1. Contexto de notificações#

Arquivo: app/context/ToastContext.tsx

O ToastProvider disponibiliza um sistema de notificações temporárias para os componentes da aplicação. O hook useToast permite acessar as operações de notificação dentro do contexto.

O hook deve ser utilizado dentro de um ToastProvider. Caso contrário, um erro é lançado para indicar que o contexto não foi configurado corretamente.

Recursos#

• Adicionar uma notificação.
• Remover uma notificação específica.
• Limpar todas as notificações.
• Expirar notificações automaticamente.
• Gerenciar referências de timeout para evitar temporizadores pendentes após a remoção dos toasts.

Integração#

O ToastProvider deve envolver a parte da árvore React que precisa acessar as notificações. Os componentes descendentes podem utilizar useToast para acionar as operações disponíveis.

2. Hooks de dados e testes#

Arquivo: hooks/useLabTests.ts

Os hooks deste módulo encapsulam operações de consulta e persistência relacionadas aos testes do LabTest, reduzindo a necessidade de implementar a mesma lógica diretamente nas páginas e nos componentes.

Tratamento de estados#

Os hooks expõem estados de carregamento e erro para permitir que a interface apresente feedback adequado durante as consultas e operações.

As operações persistentes utilizam as rotas da aplicação documentadas em Referência de APIs.

3. Hook de cálculo de pontuação#

Arquivo: hooks/useScoreCalculator.ts

O hook useScoreCalculator(data) mantém os valores das missões e das penalidades e calcula os resultados utilizados no placar.

Resultados calculados#

• Pontuação individual de cada missão.
• Soma da pontuação das missões.
• Faixa de penalidade aplicável.
• Pontuação final.

O hook utiliza useMemo para evitar recalcular os resultados quando os dados de entrada não mudam.

4. Hook do mapa de calor#

Arquivo: hooks/useHeatmap.ts

O hook useHeatmap() gerencia os pontos, as configurações e o histórico de alterações do mapa de calor.

Operações disponíveis#

Histórico de alterações#

O hook mantém um histórico interno que permite desfazer alterações sem exigir que a página conheça os detalhes de implementação do reducer.

Essa separação concentra o gerenciamento do estado no hook e simplifica sua integração com os componentes da interface.

5. Organização do código#

A lógica reutilizável está distribuída entre diretórios com responsabilidades distintas.

6. Documentação relacionada#

• Páginas e rotas — catálogo de páginas e caminhos da aplicação.
• Referência de APIs — documentação dos endpoints utilizados pelo sistema.
• Utilitários e regras de negócio — funções compartilhadas e lógica de domínio.