astro-overflow-split

v1.0.1

Published

4 months ago

Control de overflow de contenedores con alto y ancho fijo para Astro sin SSR

Downloads

0High
0Medium
0Low

victorarangodev

astro overflow container split vanilla-js web-components

Astro Overflow Splitter

Un paquete NPM para el control de overflow de contenedores con alto y ancho fijo, diseñado específicamente para Astro sin necesidad de Server-Side Rendering (SSR).

🚀 Características

✅ Compatible con Astro - Funciona completamente en el cliente
🌐 Web Components - Sin dependencias de React o frameworks
📱 Responsive - Se adapta a diferentes tamaños de pantalla
🎨 Personalizable - Estilos y opciones configurables
⚡ Ligero - Solo vanilla JavaScript y CSS
🔧 API Programática - Manipulación dinámica de elementos
📊 Multi-nivel - Distribución automática en múltiples contenedores

📦 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

🚀 Uso Rápido

1. Uso Básico con Web Component

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

<html>
<head>
  <title>Mi App</title>
</head>
<body>
  <overflow-splitter
    primary-height="200"
    overflow-max-height="300"
    container-width="256"
    items='["Elemento 1", "Elemento 2", "Elemento 3", "Elemento 4", "Elemento 5"]'
  ></overflow-splitter>

  <script>
    import 'astro-overflow-splitter';
  </script>
</body>
</html>

2. Uso Programático

---
// 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>

3. Uso Directo de la Clase

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

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

<script>
  import { createOverflowSplitter } from 'astro-overflow-splitter';
  
  const { splitter, levels, hasOverflow } = createOverflowSplitter(
    document.getElementById('direct-container'),
    { 
      primaryHeight: 200, 
      overflowMaxHeight: 300, 
      containerWidth: 256 
    },
    ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5']
  );
  
  console.log('Niveles:', levels);
  console.log('Tiene overflow:', hasOverflow);
</script>

⚙️ Opciones de Configuración

Atributos del Web Component

| Atributo | Tipo | Default | Descripción | |----------|------|---------|-------------| | primary-height | number | 200 | Altura del contenedor principal en píxeles | | overflow-max-height | number | 300 | Altura máxima de contenedores overflow | | container-width | number | 256 | Ancho de los contenedores en píxeles | | item-height | number | 60 | Altura estimada de cada elemento | | item-margin | number | 8 | Margen entre elementos | | max-levels | number | 10 | Número máximo de niveles de overflow | | items | string | [] | Array de elementos (JSON string) | | show-overflow-badge | boolean | true | Mostrar badge de overflow |

Opciones de la Clase

interface OverflowSplitterOptions {
  primaryHeight: number;        // Altura del contenedor principal
  overflowMaxHeight?: number;   // Altura máxima de overflow (default: 300)
  containerWidth?: number;      // Ancho del contenedor (default: 256)
  itemHeight?: number;          // Altura del elemento (default: 60)
  itemMargin?: number;          // Margen del elemento (default: 8)
  maxLevels?: number;           // Máximo de niveles (default: 10)
}

🎨 Personalización de Estilos

Clases CSS Personalizables

<overflow-splitter
  container-class="mi-contenedor"
  item-class="mi-elemento"
  title-class="mi-titulo"
  badge-class="mi-badge"
></overflow-splitter>

Estilos CSS Personalizados

/* Personalizar contenedor */
.mi-contenedor {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border: 3px solid #4c1d95;
  border-radius: 12px;
}

/* Personalizar elementos */
.mi-elemento {
  background: rgba(255, 255, 255, 0.9);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

/* Personalizar título */
.mi-titulo {
  color: #ffffff;
  font-weight: 700;
  text-shadow: 0 2px 4px rgba(0, 0, 0, 0.3);
}

/* Personalizar badge */
.mi-badge {
  background: #fbbf24;
  color: #92400e;
  font-weight: 600;
}

🔧 API Programática

Métodos del Web Component

const element = document.querySelector('overflow-splitter');

// Cambiar elementos
element.setItems(['Nuevo 1', 'Nuevo 2', 'Nuevo 3']);

// Agregar elemento
element.addItem('Nuevo elemento');

// Remover elemento
element.removeItem(0);

// Actualizar opciones
element.updateOptions({ primaryHeight: 250 });

// Obtener información
const levels = element.getLevels();
const hasOverflow = element.hasOverflow();

Métodos de la Clase

import { OverflowSplitter } from 'astro-overflow-splitter';

const splitter = new OverflowSplitter({
  primaryHeight: 200,
  overflowMaxHeight: 300
});

// Calcular niveles
const levels = splitter.calculateLevels(['Item 1', 'Item 2', 'Item 3']);

// Verificar overflow
const hasOverflow = splitter.hasOverflow();

// Obtener información
const levelCount = splitter.getLevelCount();
const totalItems = splitter.getTotalItemCount();

// Actualizar opciones
splitter.updateOptions({ primaryHeight: 250 }, ['Item 1', 'Item 2']);

📱 Responsive Design

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

Desktop: Contenedores en fila horizontal con scroll
Tablet: Contenedores se ajustan al ancho disponible
Mobile: Contenedores se apilan verticalmente

🌐 Compatibilidad de Navegadores

✅ Chrome 67+
✅ Firefox 63+
✅ Safari 10.1+
✅ Edge 79+
✅ Opera 54+

📚 Ejemplos Completos

Ejemplo 1: Lista de Productos

---
const productos = [
  'Laptop Gaming Pro',
  'Mouse Inalámbrico',
  'Teclado Mecánico',
  'Monitor 4K',
  'Auriculares Bluetooth',
  'Webcam HD',
  'Micrófono USB',
  'Altavoces 2.1',
  'Tableta Gráfica',
  'Disco SSD 1TB'
];
---

<overflow-splitter
  primary-height="300"
  overflow-max-height="250"
  container-width="300"
  items={JSON.stringify(productos)}
  container-class="producto-contenedor"
  item-class="producto-item"
></overflow-splitter>

Ejemplo 2: Dashboard con Widgets

---
const widgets = [
  'Gráfico de Ventas',
  'Métricas de Usuarios',
  'Lista de Tareas',
  'Calendario de Eventos',
  'Notificaciones',
  'Estadísticas',
  'Configuración',
  'Reportes'
];
---

<overflow-splitter
  primary-height="400"
  overflow-max-height="350"
  container-width="320"
  items={JSON.stringify(widgets)}
  show-overflow-badge="true"
></overflow-splitter>

🚀 Migración desde React

Si estás migrando desde la versión React:

Antes (React)

import { useMultiLevelOverflow } from './hooks/useMultiLevelOverflow';

const MyComponent = () => {
  const { levels, hasAnyOverflow } = useMultiLevelOverflow({
    items: ['Item 1', 'Item 2'],
    primaryHeight: 200,
    overflowMaxHeight: 300
  });
  
  return <OverflowContainer items={levels[0].items} />;
};

Después (Astro)

<overflow-splitter
  primary-height="200"
  overflow-max-height="300"
  items='["Item 1", "Item 2"]'
></overflow-splitter>

🤝 Contribuir

Fork el proyecto
Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
Commit tus cambios (git commit -m 'Add some AmazingFeature')
Push a la rama (git push origin feature/AmazingFeature)
Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT - ver el archivo LICENSE para detalles.

🆘 Soporte

🙏 Agradecimientos

Inspirado en el sistema de overflow multi-nivel original
Diseñado para la comunidad de Astro
Construido con Web Components estándar

¿Te gustó este paquete? ¡Dale una ⭐ en GitHub!