Documentación para desarrolladores de Listas

Las listas son la capa de contenido dinámico en FaceFlow.

Permiten a usuarios técnicos definir cómo se seleccionan, renderizan, paginan y publican colecciones de contenido dentro de una experiencia de Page sin convertir cada archivo o directorio en una edición manual de página.

Responsabilidad principal

Una Lista se encarga de:

seleccionar un conjunto de contenido
ordenar y limitar resultados
renderizar cada elemento de forma coherente
paginar colecciones grandes
exponer un contrato de navegación predecible

Las Listas deben responder una pregunta clara: "¿de qué colección es responsable esta página al presentarla?"

Modelo de Lista

Una Lista típica combina:

una definición de consulta
una estrategia de ordenación de resultados
un tamaño de página
un modo de renderizado
campos personalizados opcionales
lógica de plantilla de elemento opcional

Conceptualmente:

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

Contrato de consulta

Los equipos técnicos deben mantener las consultas de Lista explícitas y acotadas.

Entradas típicas incluyen:

tipo de contenido
límite de sección
ordenación
límite de resultados
restricciones de filtro adicionales

Una consulta débil crea una salida débil. Si el límite de contenido es vago, la Lista rápidamente se convierte en un vertedero.

Ejemplo:

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

Esa consulta es comprensible. Un archivo genérico con varios tipos no relacionados usualmente no lo es.

Ejemplo de diseño de consulta

Las buenas definiciones de Lista suelen mantener separadas la regla de selección y la regla de presentación:

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

Eso facilita revisar si el límite de contenido es correcto antes de discutir la presentación.

Modos de renderizado

Las Listas suelen seguir uno de dos modelos.

Salida estilo tarjeta

Usar esto cuando:

los editores necesitan una vía de configuración de baja fricción
el archivo sigue un patrón visual estándar
un contrato de tarjeta consistente es suficiente

Salida con plantilla personalizada

Usar esto cuando:

los elementos de resultado necesitan un mapeo más rico
el diseño no es una simple cuadrícula de tarjetas
metadatos, insignias o medios necesitan colocación personalizada
el archivo depende de la lógica de Facet

Ejemplo de salida de elemento 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>

Paginación

La paginación es parte del contrato de la Lista, no sólo un detalle visual.

La revisión técnica debe definir:

tamaño de página por defecto
comportamiento del recuento de páginas
patrón de navegación
comportamiento en estado vacío

Conceptualmente:

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

Si se espera que una Lista crezca, la paginación debe ser intencional desde el primer lanzamiento.

Relación con Páginas y Componentes

El modelo mental limpio es:

Diseño proporciona la estructura
Página proporciona la ruta publicable y la experiencia circundante
Lista proporciona la colección dinámica
Componente puede proporcionar secciones de soporte alrededor de la Lista

Ejemplo de composición de página:

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

Esto mantiene la navegación dinámica separada del contenido de página puntual.

Ejemplo de plantilla 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>

El objetivo es un contrato estable entre la consulta de la Lista y la plantilla del archivo.

Reglas para estado vacío y crecimiento

La revisión técnica también debe tener en cuenta qué ocurre cuando la colección cambia de forma:

sin resultados
un resultado
muchas páginas de resultados
campos opcionales que faltan en algunos elementos

Una plantilla de Lista solo es estable si sobrevive las cuatro condiciones sin romper el diseño ni producir una salida confusa.

Lista de verificación para revisión técnica

¿el límite de la consulta es claro y estrecho?
¿la ordenación coincide con la intención de navegación?
¿la plantilla puede manejar el crecimiento en volumen de resultados?
¿la paginación es parte del contrato de diseño?
¿la Lista resuelve un problema de archivo, no varios no relacionados?

Antipatrones

Evitar:

mezclar tipos de contenido no relacionados en un mismo archivo sólo porque están disponibles
construir un archivo completamente a mano con tarjetas manuales repetidas
usar una Lista para varios modos visuales con contratos incompatibles
dejar el orden de resultados implícito
ignorar estados vacíos y paginación hasta que el volumen de contenido sea un problema

FaceFlow Lists — Dynamic Content Listings