# ComponentBuilder
> Componha mensagens Components V2 com builders tipados, templates reutilizáveis e integração direta com o runtime do Core.

- Área: Componentes
- URL humana: https://ninenity.vercel.app/doc/component-builder
- URL Markdown: https://ninenity.vercel.app/doc/markdown/component-builder
- Pacotes e conceitos: @ninenity/componentbuilder, Components V2, Templates

## O que o ComponentBuilder resolve

Ele representa a mensagem como uma árvore validável antes de converter o documento para o formato aceito pelo Discord.js.

- **Composição**: Builders pequenos representam texto, seções, botões, selects, galerias e containers.
- **Validação**: Limites do Discord são verificados antes de a mensagem chegar à API.
- **Runtime**: Callbacks, prompts e paginações são conectados automaticamente ao Core.

O fluxo possui quatro etapas: você monta builders, gera um `ComponentTemplate`, converte o documento com `toDiscordMessagePayload()` e envia pela interação do Discord.

### fluxo mínimo

```text

const template = new MessageBuilder()
  .addComponents(
    new ContainerBuilder().addTextDisplayComponents(
      new TextDisplayBuilder().setContent('Olá, Components V2!')
    )
  )
  .template()

await interaction.reply({
  ...toDiscordMessagePayload(template.document()),
  flags: MessageFlags.IsComponentsV2
})
```


## As quatro camadas

| Camada | Papel | Exemplos |
| --- | --- | --- |
| Mensagem | Payload completo | `MessageBuilder` |
| Layout | Organiza a hierarquia visual | `ContainerBuilder`, `SectionBuilder`, `ActionRowBuilder` |
| Conteúdo | Mostra informação | `TextDisplayBuilder`, `MediaGalleryBuilder`, `FileBuilder` |
| Interação | Recebe ações do usuário | `ButtonBuilder` e builders de select |

> **Builder não é a mensagem enviada:** O builder é mutável enquanto você monta. `build()` gera um documento simples; `template()` gera um objeto reutilizável capaz de renderizar variáveis.

## Imports recomendados

Importe Discord.js pelo Core e os builders visuais pelo ComponentBuilder.

### imports.ts

```text

import {
  MessageFlags,
  SlashCommandBuilder
} from '@ninenity/core'

import {
  ActionRowBuilder,
  ButtonBuilder,
  ButtonStyle,
  ContainerBuilder,
  MessageBuilder,
  SectionBuilder,
  TextDisplayBuilder,
  toDiscordMessagePayload,
  type MessageActionRowComponentBuilder
} from '@ninenity/componentbuilder'
```


- Use `MessageFlags.IsComponentsV2` ao enviar uma árvore Components V2.
- Adicione `MessageFlags.Ephemeral` quando a resposta só deve aparecer para o autor.
- Use o tipo `MessageActionRowComponentBuilder` no `ActionRowBuilder` quando misturar builders interativos.
- Não importe APIs internas de `src`; use apenas os exports do pacote.

## Documento, template e payload

Cada representação existe para um momento diferente do fluxo.

### três representações

```text

const builder = new MessageBuilder().setContent('Status: pronto')

// Objeto serializável do ComponentBuilder
const document = builder.build()

// Reutilizável, renderizável e exportável
const template = builder.template({ name: 'status-card' })

// Payload final para interaction.reply/update
const payload = toDiscordMessagePayload(template.document())
```


| Método | Retorna | Use quando |
| --- | --- | --- |
| `build()` | `MessageDocument` | Precisa inspecionar ou serializar a árvore |
| `template()` | `ComponentTemplate` | Vai reutilizar, renderizar tokens ou registrar páginas |
| `template.document()` | `MessageDocument` | Vai converter e enviar ao Discord |
| `toDiscordMessagePayload()` | Payload Discord.js | Etapa imediatamente anterior a `reply()` ou `update()` |

## Limites estruturais

O Builder Studio e a biblioteca aplicam os limites mais importantes antes do envio.

| Estrutura | Regra |
| --- | --- |
| Mensagem | Até 40 componentes na árvore |
| Container | Até 10 filhos e sem containers aninhados |
| Action row | Até 5 botões ou um único select |
| Section | Acessório deve ser botão ou thumbnail |
| Galeria | Entre 1 e 10 imagens |
| Interativos | Cada `customId` deve ser único na mensagem |

> **Valide no ponto de criação:** Se dados externos geram componentes, limite a coleção antes de chamar o builder. Não espere o Discord rejeitar um payload grande para descobrir o problema.

## Escolha o próximo tópico

- **Mensagens V2**: Layouts completos com seções, mídia, botões e selects. ([Abrir tópico](https://ninenity.vercel.app/doc/mensagens-v2))
- **Callbacks**: Como tratar cliques e seleções sem registradores duplicados. ([Abrir tópico](https://ninenity.vercel.app/doc/callbacks))
- **Prompts**: Fluxos de confirmação com páginas de resultado. ([Abrir tópico](https://ninenity.vercel.app/doc/prompts))
- **Paginação**: Páginas estáticas, dinâmicas e controles personalizados. ([Abrir tópico](https://ninenity.vercel.app/doc/paginacao))