Documentação para Desenvolvedores de Listas

As Listas são a camada de conteúdo dinâmica no FaceFlow.

Elas permitem que usuários técnicos definam como coleções de conteúdo são selecionadas, renderizadas, paginadas e publicadas dentro de uma experiência de Página sem converter cada arquivo ou diretório em edição manual de páginas.

Responsabilidade Principal

Uma Lista é responsável por:

selecionar um conjunto de conteúdo
ordenar e limitar resultados
renderizar cada item de forma consistente
paginar coleções maiores
expor um contrato de navegação previsível

As Listas devem responder a uma pergunta clara: "qual coleção esta página é responsável por apresentar?"

Modelo de Lista

Uma Lista típica combina:

uma definição de consulta
uma estratégia de ordenação de resultados
um tamanho de página
um modo de renderização
campos personalizados opcionais
lógica de template de item opcional

Conceitualmente:

{
  "name": "resource-library",
  "query": {
    "template": "resource-item",
    "parent": "/resources/",
    "sort": "-published",
    "limit": 12
  },
  "display": {
    "mode": "custom-template",
    "pagination": true
  }
}

Contrato de Consulta

Equipes técnicas devem manter as consultas de Lista explícitas e delimitadas.

Entradas típicas incluem:

tipo de conteúdo
delimitação de seção
ordenação
limite de resultados
restrições adicionais de filtro

Uma consulta fraca gera uma saída fraca. Se a delimitação de conteúdo for vaga, a Lista rapidamente se torna um depósito de conteúdo.

Exemplo:

template=resource-item, parent=/resources/, sort=-published, limit=12

Essa consulta é compreensível. Um arquivo "catch-all" com vários tipos não relacionados geralmente não é.

Exemplo de Design de Consulta

Boas definições de Lista geralmente mantêm a regra de seleção e a regra de exibição separadas:

{
  "name": "case-studies",
  "query": {
    "template": "case-study",
    "parent": "/customers/",
    "sort": "-published",
    "limit": 9
  },
  "display": {
    "mode": "custom-template",
    "pagination": true
  }
}

Isso facilita revisar se a delimitação de conteúdo está correta antes de discutir a apresentação.

Modos de Renderização

As Listas normalmente seguem um de dois modelos.

Saída em estilo cartão

Use quando:

editores precisam de um caminho de configuração de baixa fricção
o arquivo segue um padrão visual consistente
um contrato de cartão consistente é suficiente

Saída com template personalizado

Use quando:

os itens de resultado precisam de um mapeamento mais rico
o design não é uma grade simples de cartões
metadados, emblemas ou mídia precisam de posicionamento personalizado
o arquivo depende da lógica do Facet

Exemplo de saída de item personalizada:

<div class="resource-grid">
  {{#each items}}
    <article class="resource-card">
      <a href="{{ this.url }}">
        <h3>{{ this.title }}</h3>
        <p>{{ this.summary }}</p>
      </a>
    </article>
  {{/each}}
</div>

Paginação

A paginação faz parte do contrato da Lista, não apenas um detalhe visual.

A revisão técnica deve definir:

tamanho de página padrão
comportamento da contagem de páginas
padrão de navegação
comportamento para estado vazio

Conceitualmente:

page 1 -> items 1-12
page 2 -> items 13-24
page 3 -> items 25-36

Se espera que uma Lista cresça, a paginação deve ser intencional desde o primeiro lançamento.

Relação com Páginas e Componentes

O modelo mental claro é:

Layout fornece a estrutura
Página fornece a rota publicável e a experiência ao redor
Lista fornece a coleção dinâmica
Componente pode fornecer seções de apoio ao redor da Lista

Exemplo de composição de página:

resource-layout
  -> archive-hero component
  -> resource-library list
  -> newsletter-signup component

Isso mantém a navegação dinâmica separada do conteúdo de página único.

Exemplo de Template de Lista

<section class="archive">
  <header class="archive-header">
    <h1>{{ page.title }}</h1>
  </header>

  <div class="archive-items">
    {{#each items}}
      <article class="archive-item">
        <a href="{{ this.url }}">{{ this.title }}</a>
      </article>
    {{/each}}
  </div>

  {{#if pagination}}
    <nav class="archive-pagination">
      {{{ pagination.links }}}
    </nav>
  {{/if}}
</section>

O objetivo é um contrato estável entre a consulta da Lista e o template do arquivo.

Regras de Estado Vazio e de Crescimento

A revisão técnica também deve contemplar o que acontece quando a coleção muda de formato:

nenhum resultado
um resultado
muitas páginas de resultados
campos opcionais ausentes em alguns itens

Um template de Lista é estável apenas se sobreviver a todas as quatro condições sem quebra de layout ou saída confusa.

Checklist de Revisão Técnica

a delimitação da consulta está clara e estreita?
a ordenação corresponde à intenção de navegação?
o template consegue lidar com o aumento no volume de resultados?
a paginação faz parte do contrato de design?
a Lista resolve um único problema de arquivo, e não vários problemas não relacionados?

Anti-padrões

Evitar:

misturar tipos de conteúdo não relacionados em um único arquivo apenas porque estão disponíveis
construir um arquivo inteiramente à mão com cartões manuais repetidos
usar uma única Lista para vários modos visuais com contratos incompatíveis
deixar a ordenação de resultados implícita
ignorar estados vazios e paginação até que o volume de conteúdo se torne um problema

FaceFlow Lists — Dynamic Content Listings