Astro Overflow Splitter

Un paquete NPM para el control de overflow de contenedores con alto y ancho fijo, diseñado específicamente para Astro con sistema estático que se ejecuta durante el build.

🚀 Características

• ✅ Sistema Estático - Se ejecuta durante el build de Astro, NO en el cliente
• 🌐 Sin JavaScript - Solo HTML y CSS estático en el resultado final
• 📱 Responsive - Se adapta a diferentes tamaños de pantalla
• 🎨 Personalizable - Estilos y opciones configurables
• ⚡ Ligero - No agrega peso JavaScript al bundle final
• 🔧 API Programática - Manipulación dinámica opcional
• 📊 Multi-nivel - Distribución automática en múltiples contenedores
• 🔍 SEO Friendly - Contenido indexable por motores de búsqueda

📦 Instalación

npm install astro-overflow-splitter

🎯 Casos de Uso

• Dashboards - Distribuir widgets cuando hay demasiados para mostrar
• Listas de productos - Mostrar productos en múltiples columnas
• Notificaciones - Organizar notificaciones por niveles de prioridad
• Menús dinámicos - Crear menús que se adapten al contenido
• Galerías - Organizar imágenes o tarjetas en contenedores
• Contenido estático - Cualquier lista que necesite distribución automática

🚀 Uso Rápido

1. Uso Estático (RECOMENDADO) - Sin JavaScript

---
// En tu archivo .astro
import StaticOverflowSplitter from 'astro-overflow-splitter/StaticOverflowSplitter.astro';

const items = [
  'Elemento 1', 'Elemento 2', 'Elemento 3', 'Elemento 4', 'Elemento 5',
  'Elemento 6', 'Elemento 7', 'Elemento 8', 'Elemento 9', 'Elemento 10'
];
---

<StaticOverflowSplitter
  items={items}
  primaryHeight={200}
  overflowMaxHeight={300}
  containerWidth={256}
  layout="horizontal"
  showOverflowIndicator={true}
/>

2. Uso Programático (Opcional)

---
// En tu archivo .astro
---

<div id="overflow-container"></div>

<script>
  import { 
    createOverflowSplitterElement,
    initOverflowSplitter 
  } from 'astro-overflow-splitter';
  
  // Inicializar
  initOverflowSplitter();
  
  // Crear elemento programáticamente
  const element = createOverflowSplitterElement({
    primaryHeight: 200,
    overflowMaxHeight: 300,
    containerWidth: 256,
    showOverflowBadge: true
  }, [
    'Elemento 1',
    'Elemento 2',
    'Elemento 3',
    'Elemento 4',
    'Elemento 5'
  ]);
  
  document.getElementById('overflow-container').appendChild(element);
</script>

⚙️ Opciones de Configuración

Propiedades del Componente Estático

| Propiedad | Tipo | Default | Descripción | |-----------|------|---------|-------------| | items | string[] | [] | Requerido - Lista de elementos a distribuir | | primaryHeight | number | 200 | Altura del contenedor principal | | overflowMaxHeight | number | 300 | Altura máxima de contenedores de overflow | | containerWidth | number | 256 | Ancho de todos los contenedores | | itemHeight | number | 60 | Altura de cada elemento individual | | itemMargin | number | 8 | Margen entre elementos | | maxLevels | number | 10 | Número máximo de contenedores | | layout | 'horizontal' \| 'vertical' | 'horizontal' | Dirección de distribución | | gap | number | 16 | Espacio entre contenedores | | showOverflowIndicator | boolean | false | Mostrar indicador de overflow | | containerClass | string | 'overflow-container' | Clase CSS para contenedores | | itemClass | string | 'overflow-item' | Clase CSS para elementos |

🎨 Personalización de Estilos

CSS Variables Disponibles

.static-overflow-wrapper {
  --gap: 16px; /* Espacio entre contenedores */
}

.main-container {
  border-color: #3b82f6; /* Color del contenedor principal */
}

.overflow-container {
  border-color: #d1d5db; /* Color de contenedores de overflow */
}

.overflow-item {
  background: #f9fafb; /* Fondo de elementos */
  border-color: #e5e7eb; /* Borde de elementos */
}

Clases CSS Personalizables

/* Contenedor principal */
.main-container {
  /* Estilos personalizados */
}

/* Contenedores de overflow */
.overflow-container {
  /* Estilos personalizados */
}

/* Elementos individuales */
.overflow-item {
  /* Estilos personalizados */
}

/* Indicador de overflow */
.overflow-indicator {
  /* Estilos personalizados */
}

🔧 Uso Avanzado

1. Layout Vertical

<StaticOverflowSplitter
  items={items}
  layout="vertical"
  primaryHeight={150}
  overflowMaxHeight={200}
/>

2. Sin Indicador de Overflow

<StaticOverflowSplitter
  items={items}
  showOverflowIndicator={false}
/>

3. Clases CSS Personalizadas

<StaticOverflowSplitter
  items={items}
  containerClass="mi-contenedor"
  itemClass="mi-elemento"
/>

4. Con Slots de Astro

<StaticOverflowSplitter items={items}>
  <div slot="before">
    <h3>Lista de Elementos</h3>
  </div>
  
  <div slot="after">
    <p>Total: {items.length} elementos</p>
  </div>
</StaticOverflowSplitter>

📊 Cálculo de Overflow

El sistema calcula automáticamente cuántos elementos caben en cada contenedor:

Elementos por contenedor = (altura - padding) / (itemHeight + itemMargin)

Ejemplo:

• primaryHeight: 200px
• itemHeight: 60px
• itemMargin: 8px
• padding: 24px (12px arriba + 12px abajo)

Resultado:

• Elementos por contenedor = (200 - 24) / (60 + 8) = 176 / 68 ≈ 2.6
• 2 elementos caben en el contenedor principal
• Los elementos restantes van a contenedores de overflow

🚀 Ventajas del Sistema Estático

✅ Durante el Build:

• Cálculo automático de distribución
• Generación de HTML optimizado
• Validación de datos
• Optimización de rendimiento

✅ En el Cliente:

• Cero JavaScript en el HTML final
• HTML puro y CSS
• Carga instantánea
• SEO perfecto
• Accesibilidad nativa

✅ Rendimiento:

• No hay hidratación
• No hay JavaScript que ejecutar
• No hay re-renders
• Página completamente estática

📱 Responsive Design

El componente se adapta automáticamente a diferentes tamaños de pantalla:

@media (max-width: 768px) {
  .static-overflow-wrapper[data-layout="horizontal"] {
    flex-direction: column;
    overflow-x: visible;
  }
  
  .overflow-containers-wrapper {
    flex-direction: column;
  }
}

🔍 SEO y Accesibilidad

• Contenido indexable por motores de búsqueda
• Estructura semántica clara
• Navegación por teclado nativa
• Screen readers compatibles
• HTML válido y estándar

📚 Ejemplos Completos

Lista de Productos

---
import StaticOverflowSplitter from 'astro-overflow-splitter/StaticOverflowSplitter.astro';

const products = [
  'MacBook Pro 16" M3 Max - $3,499',
  'iPhone 15 Pro Max 256GB - $1,199',
  'iPad Air 5ta Gen WiFi 64GB - $599',
  // ... más productos
];
---

<StaticOverflowSplitter
  items={products}
  primaryHeight={200}
  overflowMaxHeight={250}
  containerWidth={280}
  layout="horizontal"
  showOverflowIndicator={true}
/>

Notificaciones

---
import StaticOverflowSplitter from 'astro-overflow-splitter/StaticOverflowSplitter.astro';

const notifications = [
  'Nueva actualización disponible',
  'Mensaje de Juan Pérez',
  'Recordatorio: Reunión a las 3pm',
  // ... más notificaciones
];
---

<StaticOverflowSplitter
  items={notifications}
  primaryHeight={180}
  overflowMaxHeight={220}
  containerWidth={320}
  layout="vertical"
  showOverflowIndicator={true}
/>

🆘 Solución de Problemas

Problema: Elementos no se distribuyen

Solución: Verificar que itemHeight + itemMargin sea menor que primaryHeight

Problema: Contenedores muy anchos

Solución: Ajustar containerWidth y usar layout="vertical"

Problema: Espaciado incorrecto

Solución: Ajustar gap y itemMargin

📋 Checklist de Implementación

• [ ] Instalar el paquete: npm install astro-overflow-splitter
• [ ] Importar el componente: import StaticOverflowSplitter from 'astro-overflow-splitter/StaticOverflowSplitter.astro'
• [ ] Definir la lista de elementos
• [ ] Configurar dimensiones apropiadas
• [ ] Elegir layout (horizontal/vertical)
• [ ] Personalizar estilos CSS si es necesario
• [ ] Ejecutar npm run build para generar HTML estático

🎯 Casos de Uso Recomendados

✅ Perfecto para:

• Listas de productos en e-commerce
• Notificaciones del sistema
• Menús de navegación
• Galerías de imágenes
• Dashboards estáticos
• Contenido de blog

⚠️ Considerar alternativas para:

• Contenido que cambia frecuentemente
• Interacciones complejas del usuario
• Datos en tiempo real
• Filtros dinámicos

🚀 Roadmap

• [ ] Soporte para elementos con diferentes alturas
• [ ] Animaciones CSS durante hover
• [ ] Temas predefinidos
• [ ] Integración con sistemas de diseño
• [ ] Soporte para imágenes y contenido multimedia

📄 Licencia

MIT License - ver LICENSE para más detalles.

🤝 Contribuir

¡Las contribuciones son bienvenidas! Por favor, lee CONTRIBUTING.md para detalles.

Desarrollado con ❤️ para la comunidad de Astro