[ATOMS] Accordion

[egdev6]

🧩 Tarea: Accordion

Referencia:

https://www.heroui.com/docs/components/accordion

✅ Fases del desarrollo

• 1. Research de funcionalidad
  Investigar soluciones similares, patrones existentes y necesidades reales. Añadir capturas, enlaces o benchmarks si aplican.

• 2. Definición de funcionalidades
  Especificar qué debe hacer el componente: props, estados, interacción, accesibilidad, variantes, etc.

• 3. Implementación del componente
  Desarrollo del componente en base a la definición anterior. Incluir historias de Storybook si procede.

• 4. Documentación del componente

  • Storybook documentado con controles y ejemplos de uso
  • MDX o comentarios en JSDoc si aplica
  • Sección de casos de uso o guidelines

• 5. Code review y modificaciones

  • Revisión funcional
  • Revisión visual (alineamiento con el design system)
  • Corrección de errores o ajustes sugeridos

• 6. Merge en main
  Una vez aprobado, mergear la rama a main siguiendo el flujo de PR establecido. (Esta parte me encargo yo)

---

📎 Notas adicionales

Anotar cualquier comentario, decisión tomada o consideraciones especiales. (Nómbra a egdev6 para cualquier consulta)

---

🔗 Recursos relacionados

_Nombrar cualquier recurso externo

[EdoAbarca]

Investigación de funcionalidad: Accordion

Definición

Accordion es un componente UI que, al interactuar con él desde el header (o trigger), este despliega o comprime contenido desde su ubicación (panel). Su objetivo es evitar sobrealimentar al usuario con información, y permitirle acceder a esta si él lo desea.

Soluciones observadas

1. HeroUI (implementaciones modernas de componentes): https://www.heroui.com/docs/components/accordion
2. W3Schools (ejemplo clásico con JavaScript puro): https://www.w3schools.com/howto/howto_js_accordion.asp?utm_source=chatgpt.com
3. CodyHouse (patrones y accesibilidad): https://codyhouse.co/ds/components/info/accordion?utm_source=chatgpt.com
4. CodePen (ejemplo experimental): https://codepen.io/luiso2/pen/poXbYrb?utm_source=chatgpt.com
5. Aditus (énfasis en accesibilidad): https://www.aditus.io/patterns/accordion/?utm_source=chatgpt.com
6. CodeFronts (colección amplia — múltiples variantes CSS): https://codefronts.com/css-accordion/?utm_source=chatgpt.com

Patrones entre soluciones

1. Elemento disparador (trigger / header)

   • Normalmente un button dentro del header o el propio summary cuando se usa details.
   • El trigger contiene el título y, opcionalmente, un indicador/chevron.

2. Panel asociado

   • Panel con contenido que se muestra/oculta. Suele usarse aria-controls desde el trigger apuntando a id del panel.
   • El panel suele tener role="region" y aria-labelledby apuntando al trigger.

3. Estados ARIA

   • aria-expanded en el trigger (true/false).
   • aria-hidden en el panel o controlar visibilidad por CSS/DOM.

4. Gestión de apertura

   • Dos modos: single (solo un panel abierto — típico “accordion”) y multiple (varios abiertos — tipo collapsible list).
   • Opciones allowToggle (permitir cerrar un panel abierto) y allowMultiple.

5. Animaciones

   • Transición de max-height o medición dinámica de height para animar desde/ hacia auto.
   • Alternativa performant: animar opacity + transform dentro de un contenedor con overflow: hidden.

6. Keyboard / foco

   • Soporte para Enter/Space para activar el trigger.
   • Navegación entre headers con Arrow Up / Arrow Down, y Home / End para ir al primero/último.

7. Implementaciones sin JS

   • Uso de <details><summary> o input[type=checkbox] + label para CSS-only.

8. Progressive enhancement

   • Degradado elegante: funcional sin JS (summary/details), mejor experiencia con JS (animaciones, control, eventos).

Necesidades reales

• Accesibilidad completa: lectores de pantalla, gestión de foco y navegación por teclado, roles y atributos ARIA correctos.
• Predictibilidad: comportamiento consistente entre navegadores y en SSR.
• Control y extensibilidad: API que permita variantes visuales y hooks para integrar lógica (analytics, lazy load, eventos).
• Rendimiento: animaciones suaves, manejo eficiente cuando hay muchas secciones, y evitar reflows innecesarios.
• Compatibilidad con Motion Preferences: respetar prefers-reduced-motion.
• Soporte para contenido dinámico: imágenes, iframes o contenido que cambia altura (usar ResizeObserver).
• Testing y QA: facilidades para testeo (data- attributes, events) y buenas pruebas de accesibilidad (axe, jest-axe).

Definición de funcionalidades

API / Props (sugeridas)

type AccordionProps = {
  /** Elementos AccordionItem */
  children: React.ReactNode;
  /** IDs o índices abiertos por defecto (single: number | null, multiple: number[]) */
  defaultOpen?: number | number[];
  /** Controlado: índices abiertos */
  open?: number | number[];
  /** Callback cuando cambia el estado de apertura */
  onChange?: (openIndexes: number | number[]) => void;
  /** Permitir múltiples secciones abiertas */
  allowMultiple?: boolean;
  /** Permitir cerrar la última sección abierta (cuando single) */
  allowToggle?: boolean;
  /** Clase CSS para el contenedor */
  className?: string;
  /** Prefijo para generación de IDs */
  idPrefix?: string;
  /** Deshabilitar interacción */
  disabled?: boolean;
  /** Opciones de animación */
  motion?: {
    duration?: number; // ms
    easing?: string; // css easing
    reduceMotion?: boolean; // overridable
  };
};

type AccordionItemProps = {
  children: React.ReactNode; // panel content
  header: React.ReactNode; // header content (slot)
  id?: string; // opcional, para control manual
  disabled?: boolean;
  className?: string;
  headerClassName?: string;
  panelClassName?: string;
  /** lazy: renderizado perezoso del panel mientras no esté abierto */
  lazy?: boolean;
};

Notas sobre la API

• Soportar tanto modo controlado (open + onChange) como no-controlado (defaultOpen).
• allowMultiple y allowToggle permiten recrear los patrones observados.
• motion.reduceMotion o lectura automática de prefers-reduced-motion.

Estados internos necesarios

• openIndexes: Set<number> (o number si allowMultiple=false).
• focusedIndex: number para gestión del foco con flechas.
• isAnimating: Map<number, boolean> por ítem para evitar toggles conflictivos.
• measuredHeight: number por panel (si se usa medición para animar height hacia auto).

Slots (estructura de componentes)

• Accordion (wrapper)

  • AccordionItem[]

    • AccordionHeader (slot / prop header) — debe renderizar un <button> o summary

      • AccordionIndicator (chevron/ícono) — opcional

    • AccordionPanel — contenido colapsable

Permitir children compuestos para máxima flexibilidad:

<Accordion>
  <AccordionItem>
    <AccordionHeader>Title</AccordionHeader>
    <AccordionPanel>Contenido...</AccordionPanel>
  </AccordionItem>
</Accordion>

A11y (recomendaciones concretas)

Basado en el patrón WAI-ARIA para Accordions:

1. Trigger como botón

   • Usa un elemento button para el trigger. Evitar div con click handlers.
   • Añadir aria-expanded="true|false" en el button.
   • Añadir aria-controls="panel-id" apuntando al panel.

2. Panel

   • Panel con id="panel-id", role="region" y aria-labelledby="trigger-id".
   • Cuando esté oculto: hidden o aria-hidden="true" + display:none (si quieres remover del DOM accesible). Si lo mantienes en DOM para animación, usar aria-hidden.

3. Keyboard interactions

   • Enter / Space: activar toggle del panel.
   • Arrow Down / Arrow Up: mover foco al trigger siguiente/anterior.
   • Home / End: mover foco al primer/último trigger.
   • Tab mueve el foco normalmente fuera del trigger (no capturar Tab para gestión interna salvo que uses roving tabindex).
   • Implementar roving tabindex o manejar tabindex = 0 para el elemento enfocable y -1 para los demás.

4. Labels y contexto

   • Cada trigger debe tener un id único (ej. ${idPrefix}-header-${index}) y el panel su aria-labelledby apuntándolo.

5. Preferencias de movimiento

   • Respetar prefers-reduced-motion: reduce. Si está activado, desactivar animaciones y hacer cambios instantáneos.

6. Lectores de pantalla y cambios dinámicos

   • Opcionalmente emitir mensajes en un aria-live="polite" para anunciar que una sección se expandió (solo si el cambio no es obvio).
   • Evitar anunciar texto redundante que confunda al usuario.

7. Fallbacks nativos

   • Permitir renderizar <details> como fallback sencillo y accesible si se desea máximo soporte sin JS.

Variantes (UX / visuales)

• Default (card): header con borde, indicador derecho.
• Flush: sin bordes entre items (lista compacta).
• Ghost: solo texto y chevron, transparente.
• Nested: accordions dentro de panels.
• Controlled: totalmente controlado desde la app (para integrarlo con rutas, deep linking o almacenamiento del estado).
• Lazy: panels renderizados sólo al abrir (optimización para contenido pesado).
• Animated / Non-animated: opción para desactivar animaciones.
• With counters / badges: header que incluye metadata (ej. número de elementos, estado).
• Fullscreen panel: variante donde el panel ocupa un modal / full area al abrir.

Animaciones (estrategia y recomendaciones)

1. Técnicas

   • Medición dinámica (JS): medir scrollHeight del panel y animar height desde 0px a ${scrollHeight}px, luego limpiar el height para auto. Evita animar height: auto directamente.
   • CSS-only con max-height: fijar max-height grande y animar, solución simple pero frágil si el contenido puede superar el max-height.
   • Transform + opacity: animar transform: translateY() + opacity dentro de un contenedor con overflow: hidden para mejor rendimiento (no ideal si necesitas que el flujo del documento cambie con la altura).

2. Parámetros

   • Duración sugerida: 200ms–350ms.
   • Easing sugerido: cubic-bezier(0.2, 0.9, 0.2, 1) o ease.
   • Stagger ligero si abres múltiples items secuencialmente.

3. Performance

   • Usar will-change: height, opacity con moderación.
   • Para contenido que cambia su tamaño (imágenes/asíncrono), utilizar ResizeObserver para recalcular la altura objetivo y ajustar la animación en vuelo.
   • Cancelar animaciones previas al iniciar una nueva para evitar estados inconsistentes.

4. Accesibilidad de movimiento

   • Detectar prefers-reduced-motion y: reducir la duración a 0 o omitir la animación.

5. Interrupción y estado final

   • Al terminar la animación, limpiar estilos height/max-height inline para permitir el layout natural.
   • Marcar estado isAnimating para evitar toggles mientras la animación está en curso o permitir interrumpirla limpiamente.

Ejemplo (pseudo-React + notas)

En este documento no se incluye la implementación completa, pero a continuación hay un sketch de API para orientar la implementación.

// Uso propuesto
<Accordion defaultOpen={[0]} allowMultiple>
  <AccordionItem>
    <AccordionHeader>Sección 1</AccordionHeader>
    <AccordionPanel>Contenido 1...</AccordionPanel>
  </AccordionItem>
  <AccordionItem>
    <AccordionHeader>Sección 2</AccordionHeader>
    <AccordionPanel lazy>Contenido 2 (lazy)...</AccordionPanel>
  </AccordionItem>
</Accordion>

Checklist para QA / Accessibility testing

• Cada trigger es un button y tiene aria-expanded.
• Cada panel tiene role="region" y aria-labelledby apuntando al trigger.
• Navegación por teclado (Enter/Space, Arrow Up/Down, Home/End) funciona.
• prefers-reduced-motion desactiva animaciones.
• IDs únicos por ítem (sin colisiones en páginas con varios accordions).
• Lazy-loading no rompe la medición/animación del panel.
• Tests automatizados cubren apertura, cierre, y comportamiento keyboard.

---

[egdev6]

Buen análisis @EdoAbarca!! A picar!!! 🤘🤘