---
sidebar_position: 7
title: "Entendendo os Componentes"
---

As atividades de programação são montadas a partir de um conjunto de componentes reutilizáveis em `app/src/components/game/`. Entender como eles se compõem é fundamental para criar ou modificar uma atividade.

## Composição geral

```mermaid
graph TD
    GB[GameBase
composição raiz] --> GNB[GameNavBar
barra superior]
    GB --> GFI[GameFaseInfo
descrição da fase]
    GB --> PGL[PanelGroup
layout dividido]
    PGL --> EP[EditorProvider
contexto do editor]
    EP --> CH[children
BlocklyEditor ou CodeEditor]
    PGL --> GA[GameArea
canvas Phaser]
    GB --> GF[GameFooter
controles inferiores]
    GB --> SF[SeletorDeFases
modal de fases]
    GB --> SM[SucessoModal]
    GB --> FM[FalhaModal]
```

## GameBase

`app/src/components/game/GameBase.jsx`

É o componente raiz de qualquer atividade de programação. Recebe a `gameFactory` e o `gameConfig`, monta o layout dividido e instancia todos os subcomponentes.

```mermaid
flowchart LR
    ATIV["<Atividade />
(página da atividade)"] -->|"gameFactory, gameConfig"| GB[GameBase]
    GB -->|instancia| UP[usePhaser]
    GB -->|lê| GS[GameStateContext]
    GB -->|lê| GM[useGameModals]
```

Props:

| Prop | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `gameFactory` | `Function` | Sim | Função que cria a config Phaser da atividade |
| `gameConfig` | `Object` | Sim | Configuração completa: `gameId`, `gameName`, `fases`, `type` |
| `children` | `ReactNode` | Sim | O editor da atividade (normalmente `<GameEditor>` + `<BlocklyEditor>`) |
| `onHelpClick` | `Function` | Não | Callback para o botão de ajuda |
| `customFailureHandler` | `Function` | Não | Handler customizado para falhas específicas da atividade |

Arquivo de referência: `app/src/components/game/GameBase.jsx`

## GameArea

`app/src/components/game/GameArea.jsx`

Container do painel direito. Hospeda o canvas Phaser e funciona como ponte entre o `GameStateContext` e o `gameEventBus`.

```mermaid
sequenceDiagram
    participant CTX as GameStateContext
    participant GA as GameArea
    participant GEB as gameEventBus
    participant PH as Phaser (BaseGameScene)

    CTX->>GA: estado muda para EXECUTANDO
    GA->>GEB: gameEventBus.executeCode(codigo, workspace)
    PH->>GEB: emit('gameSuccess')
    GEB->>GA: ouvinte dispara
    GA->>CTX: finalizeWithSuccess()
```

Além disso, `GameArea` controla:
- **Confetti** ao detectar sucesso de fase (`ConfettiOverlay`).
- **Indicador de blocos restantes** quando a fase tem `maxBlocks`.
- **Overlay de transição** ao trocar de fase (fade de 600ms).

## GameEditor

`app/src/components/game/GameEditor.jsx`

Componente que renderiza os botões de controle da execução: Executar, Parar e Reiniciar. Lê e escreve no `GameStateContext`.

```mermaid
stateDiagram-v2
    [*] --> idle
    idle --> executando: clique Executar
    executando --> idle: clique Parar
    executando --> sucesso: gameSuccess
    executando --> falha: gameFailure
    sucesso --> idle: clique Reiniciar
    falha --> idle: clique Reiniciar
```

O componente usa um `useRef` para evitar cliques duplicados rápidos - a proteção é síncrona e não depende de re-render.

Ao ser usado em uma atividade:

```jsx
<GameEditor textoExecutar="Executar" textoReiniciar="Reiniciar">
  <BlocklyEditor toolboxGenerator={gerarToolbox} />
</GameEditor>
```

O `children` é o editor que aparece acima dos botões.

## GameNavBar

`app/src/components/game/GameNavBar.jsx`

Barra superior fixa com logo, nome da atividade e ícone de tipo (blocos ou código).

Props relevantes:

| Prop | Descrição |
|---|---|
| `title` | Nome da atividade exibido na barra |
| `type` | `'blocks'` ou `'code'` - define o ícone exibido |
| `thumbnail` | URL da imagem de capa (usada em versão mobile) |

Em telas pequenas, a navbar colapsa em um menu hambúrguer.

## GameFooter

`app/src/components/game/GameFooter.jsx`

Barra inferior com acesso ao seletor de fases, indicador da fase atual e botão de ajuda.

## GameFaseInfo

`app/src/components/game/GameFaseInfo.jsx`

Faixa logo abaixo da navbar com o título e a descrição da fase atual. Atualiza automaticamente ao trocar de fase.

## SeletorDeFases

`app/src/components/game/SeletorDeFases.jsx`

Modal com a lista de fases da atividade. Mostra quais foram concluídas, permite navegar entre elas e oferece a opção de resetar o progresso.

## SucessoModal e FalhaModal

`app/src/components/game/SucessoModal.jsx` e `FalhaModal.jsx`

Modais exibidos ao final de uma execução. Ambos mostram o código gerado pelo Blockly (sem as chamadas de `highlightBlock`).

O `SucessoModal` oferece o botão "Próxima fase" quando há mais fases disponíveis.
O `FalhaModal` oferece o botão "Tentar novamente" e exibe a mensagem de falha personalizada da fase.

## ResizeHandle

`app/src/components/game/ResizeHandle.jsx`

Alça de redimensionamento entre o painel do editor e o painel do Phaser. Em mobile, o resize é vertical; em desktop, é horizontal. Integra com a biblioteca `react-resizable-panels`.

Referência externa: https://github.com/bvaughn/react-resizable-panels
