Documentação para Desenvolvedores de Componentes

Componentes são seções de site dirigidas por esquema renderizadas através do FaceFlow.

Para usuários técnicos, Componentes são o contrato principal de seção reutilizável no sistema. Eles combinam definições de campos, saída de template do Facet, estilização opcional, comportamento opcional no cliente e reutilização com escopo.

Responsabilidade Principal

Um Componente é responsável por:

• definir um contrato de seção reutilizável
• expor um esquema de autoria controlado
• renderizar a saída através do Facet
• opcionalmente anexar estilos e comportamentos com escopo
• suportar reutilização no nível de página, layout ou site

Componentes devem resolver problemas de seção repetíveis. Não devem se tornar contêineres soltos para marcação arbitrária específica de página.

Modelo de Definição de Componente

Uma definição típica de Componente inclui:

{
  "name": "contact-section",
  "title": "Contact Section",
  "version": "1.0.0",
  "type": "component",
  "category": "contact",
  "defaultScope": "page",
  "description": "Contact section with CTA and embedded form support",
  "fields": [
    { "name": "title", "label": "Title", "type": "text" },
    { "name": "summary", "label": "Summary", "type": "textarea" },
    { "name": "contactForm", "label": "Form", "type": "formSelect" }
  ],
  "html": "<section><h2>{{ title }}</h2><p>{{ summary }}</p><div data-form-embed=\"{contactForm}\"></div></section>",
  "style": ".contact-section { padding: 4rem 0; }",
  "script": "/* optional behavior */"
}

Este modelo é o que permite que um Componente atue como um contrato de seção governado em vez de um fragmento solto de código copiado.

Metadados Principais

Campos importantes de metadados incluem:

• name
• title
• version
• type
• category
• defaultScope
• description

Orientações:

• mantenha name estável após o lançamento
• use title para clareza no editor
• atualize version intencionalmente quando o esquema ou o comportamento de renderização mudar
• escolha defaultScope com base na reutilização esperada, não pela conveniência

Esquema de Campos

O esquema de campos define o que os autores podem alterar sem alterar a estrutura da seção.

Tipos de campo de nível superior suportados incluem:

• text
• textarea
• number
• url
• date
• image
• images
• file
• select
• checkbox
• richtext
• htmlcode
• map
• repeater
• formSelect
• reviewSelect

Tipos adicionais de subcampo podem ser usados dentro de repeater, incluindo:

• color
• email
• tel
• range

Exemplo:

{
  "name": "faqItems",
  "label": "FAQ Items",
  "type": "repeater",
  "fields": [
    { "name": "question", "type": "text" },
    { "name": "answer", "type": "textarea" }
  ]
}

Escolha tipos de campo pelo intento do conteúdo, não pela conveniência. Um url deve permanecer um URL. Um conjunto repetido de cards deve ser um repeater, não vários campos de texto não relacionados.

Veja a referência completa de campos:

• Component Fields
• Repeater Field

Modelo de Template

A parte html de um Componente é renderizada através do Facet.

Isso significa que templates podem usar:

• saída de campos
• condicionais
• laços
• filtros
• contexto sensível à página
• Variáveis reutilizáveis

Exemplo:

<section class="hero-section">
  <div class="container">
    <h1>{{ title }}</h1>

    {{#if summary}}
      <p>{{ summary }}</p>
    {{/if}}

    {{#if ctaUrl}}
      <a href="{{ ctaUrl }}" class="btn-primary">{{ ctaLabel }}</a>
    {{/if}}
  </div>
</section>

Ou com um repeater:

<div class="faq-list">
  {{#each faqItems as="item"}}
    <article class="faq-item">
      <h3>{{ item.question }}</h3>
      <p>{{ item.answer }}</p>
    </article>
  {{/each}}
</div>

Para detalhes de sintaxe:

• Facet
• Facet Template Syntax

Modelo de Escopo

Componentes podem existir em três níveis de reutilização:

• site
• layout
• page

Conceitualmente:

site scope   -> reusable across the broader site
layout scope -> shared inside one page family
page scope   -> local to one page

O escopo determina tanto a visibilidade quanto o impacto das alterações. Se um Componente mudar no escopo do site, isso é uma mudança arquitetural ampla, não uma edição local.

Para o modelo mais amplo:

• Scope System

Comportamento de Renderização

No tempo de renderização, o FaceFlow resolve a instância do Componente combinando:

• a definição do Componente
• valores de campo salvos
• contexto de renderização atual
• serviços de runtime relacionados, como mídia, Variáveis, Formulários e Avaliações

Conceitualmente:

component definition
  + saved field values
  + runtime context
  -> Facet render
  -> final section output

Este é o ponto onde os dados dos campos se tornam marcação em tempo de execução.

Estilos e Comportamento

Componentes podem anexar estilos opcionais e comportamento opcional.

Exemplo:

.pricing-card {
  border-radius: 1rem;
  padding: 2rem;
}

document.querySelectorAll('.faq-item button').forEach((button) => {
  button.addEventListener('click', () => {
    button.closest('.faq-item').classList.toggle('is-open');
  });
});

Use isto com parcimônia. A maior parte do comportamento da seção deve permanecer simples, previsível e fácil de manter.

Formulários e Avaliações Dentro de Componentes

Dois tipos de campo são especialmente importantes para seções interativas:

• formSelect
• reviewSelect

Eles permitem que Componentes incorporem fluxos de trabalho de negócio sem codificar rigidamente um modelo específico.

Marcadores típicos:

<div data-form-embed="{contactForm}"></div>
<div data-review-embed="{serviceReview}"></div>

Isso mantém a seção reutilizável enquanto permite que o Formulário ou o modelo de Avaliação selecionado mude no momento da autoria.

Padrões de Componentes (Exemplos)

Basic content section:

fields:
  title
  summary
template:
  heading + paragraph

FAQ section:

fields:
  faqItems repeater
template:
  each item -> question + answer

Lead capture section:

fields:
  title
  summary
  contactForm (formSelect)
template:
  copy + data-form-embed marker

Lista de Verificação Técnica

• o Componente resolve um problema de seção repetível?
• o esquema de campos está claro e intencional?
• o template é legível e estável?
• o escopo escolhido está correto para a reutilização esperada?
• um editor futuro entenderia como usá-lo apenas pelo contrato de campos?

Antipadrões

Evite:

• sobrecarregar um Componente com casos de uso não relacionados
• adicionar lógica de negócio específica de página que deveria ficar fora do contrato da seção
• usar htmlcode quando um modelo de campo estruturado seria mais seguro
• ampliar o escopo só porque a seção pode ser reutilizada algum dia
• renomear campos depois que o conteúdo já foi armazenado para eles

Quando Dividir um Componente

Divida um Componente quando:

• o esquema de campos se tornar muito amplo
• vários layouts ou contextos de página precisarem de versões conflitantes
• o template estiver cheio de exceções e ramificações pontuais
• editores não entenderem mais o que a seção deveria fazer

Se o contrato deixar de ser claro, a reutilização normalmente deixa de ser valiosa.

Relacionado

• Components Product Overview
• Component Guide
• Component Fields
• Pages
• Layouts
• Forms
• Reviews