snk-data-grid (TypeScript Puro)

snk-data-grid es una biblioteca de DataGrid (tabla de datos) reactiva, potente y de alto rendimiento escrita en TypeScript puro (Vanilla TS / JS), sin dependencias de frameworks externos como Angular, React o Vue. Puede ser utilizada en cualquier proyecto web, aplicación SPA, Vanilla JS, o integrada fácilmente en cualquier framework.

🚀 Características Principales

• Filtro Checklist (Tipo Excel): Filtrado interactivo mediante selección múltiple de valores únicos con buscador interno integrado y casilla de "Seleccionar todo".
• Filtro de Texto por Columna: Búsqueda rápida por texto en cada columna posicionada debajo de las cabeceras.
• Cabeceras Multinivel: Soporte para columnas anidadas con cálculo automático y recursivo de colspan y rowspan.
• Agrupación Dinámica (Drag & Drop): Agrupa filas arrastrando columnas a la zona superior de agrupación, reordena niveles de grupo y colapsa/expande subárboles.
• Filtro en Columnas Agrupadas: Permite filtrar valores específicos directamente desde los badges de agrupación.
• Ordenación (Sorting): Ordenamiento ascendente y descendente con soporte natural numérico y alfabético.
• Edición en Línea: Edición directa en celda con doble clic (texto, números, fechas y booleanos), confirmación con Enter/blur y cancelación con Escape.
• Reordenamiento de Filas: Arrastrar y soltar filas (Drag & Drop) para cambiar su orden con evento emitido.
• Redimensionamiento de Columnas: Control táctil y con cursor para ajustar el ancho de cada columna.
• Agregados y Totales: Cálculo automático de sumas y conteos para subtotales de grupo y fila de total general.
• Exportación Completa: Descarga de datos en formato Excel (.xlsx respetando la jerarquía del árbol de grupos, subtotales y totales), CSV (con UTF-8 BOM) y JSON.
• Visibilidad de Columnas: Menú desplegable interactivo para mostrar u ocultar columnas en tiempo real.
• Renderizado y Plantillas Personalizadas: Función cellRenderer o plantillas templates para renderizar badges, botones, HTML enriquecido o nodos del DOM.
• Estilos Automáticos: Inyección de CSS integrada o uso de archivo .css/.scss independiente con variables CSS (--snk-primary, etc.).

📦 Instalación

npm install snk-data-grid

💻 Uso Rápido en TypeScript / JavaScript

1. En HTML

<div id="mi-grid" style="max-width: 1200px; margin: 20px auto;"></div>

2. En TypeScript / JavaScript

import { SnkDataGrid, SnkGridColumnDef } from 'snk-data-grid';
// Opcional si deseas importar el CSS manualmente:
// import 'snk-data-grid/dist/snk-data-grid.css';

// 1. Definición de Columnas
const columnas: SnkGridColumnDef[] = [
  { field: 'id', header: 'ID', type: 'number', width: '80px', sortable: true },
  { field: 'nombre', header: 'Nombre Completo', type: 'string', filterable: true, sortable: true, editable: true, showTextFilter: true },
  { field: 'departamento', header: 'Departamento', type: 'string', filterable: true, groupable: true, defaultGroupOrder: 1 },
  { field: 'cargo', header: 'Cargo', type: 'string', filterable: true },
  { field: 'salario', header: 'Salario', type: 'number', aggregate: 'sum', width: '120px' },
  {
    field: 'estado',
    header: 'Estado',
    type: 'string',
    filterable: true,
    width: '120px',
    cellRenderer: (item) => {
      const isActivo = item.estado === 'Activo';
      return `<span style="padding: 4px 8px; border-radius: 12px; font-size: 11px; font-weight: bold; background-color: ${isActivo ? '#d1e7dd' : '#f8d7da'}; color: ${isActivo ? '#0f5132' : '#842029'};">${item.estado.toUpperCase()}</span>`;
    }
  }
];

// 2. Datos
const empleados = [
  { id: 1, nombre: 'Ana García', departamento: 'Tecnología', cargo: 'Desarrolladora Frontend', salario: 4500, estado: 'Activo' },
  { id: 2, nombre: 'Carlos López', departamento: 'Tecnología', cargo: 'Desarrollador Backend', salario: 5200, estado: 'Activo' },
  { id: 3, nombre: 'María Rodríguez', departamento: 'Ventas', cargo: 'Ejecutiva de Cuentas', salario: 3100, estado: 'Inactivo' },
  { id: 4, nombre: 'Juan Pérez', departamento: 'Ventas', cargo: 'Director Comercial', salario: 7500, estado: 'Activo' },
  { id: 5, nombre: 'Laura Gómez', departamento: 'Recursos Humanos', cargo: 'Analista de Selección', salario: 2800, estado: 'Activo' }
];

// 3. Instanciación del Grid
const grid = new SnkDataGrid('#mi-grid', {
  columns: columnas,
  data: empleados,
  showColumnButton: true,
  showExcelButton: true,
  showCsvButton: true,
  showJsonButton: true,
  allowRowReordering: true,
  defaultPageSize: 5,
  actionColumnWidth: '140px',
  actionRenderer: (item) => {
    return `
      <div style="display: flex; gap: 6px; justify-content: center;">
        <button class="snk-btn snk-btn-outline" onclick="alert('Editando a ${item.nombre}')" style="padding: 2px 8px; font-size: 11px;">Editar</button>
      </div>
    `;
  },
  onCellEdit: (e) => {
    console.log('Celda editada:', e.field, 'Nuevo valor:', e.value, 'Item:', e.item);
  },
  onRowReorder: (e) => {
    console.log('Fila reordenada:', e.draggedItem, '-> Soltada en:', e.dropTargetItem);
  }
});

🛠️ Referencia de Configuración (SnkGridOptions)

| Propiedad | Tipo | Por Defecto | Descripción | | :--- | :--- | :--- | :--- | | columns | SnkGridColumnDef[] | (Requerido) | Configuración de las columnas de la tabla. | | data | any[] | (Requerido) | Arreglo de datos a mostrar. | | actionRenderer | (item: any, index: number) => HTMLElement \| string | undefined | Función para renderizar la columna de acciones CRUD. | | actionColumnWidth | string | '120px' | Ancho de la columna de acciones. | | defaultPageSize | number | 10 | Tamaño de página por defecto. | | pageSizeOptions | number[] | [5, 10, 20] | Opciones de tamaño de página disponibles. | | showColumnButton | boolean | false | Muestra el botón para abrir el menú de selección de columnas. | | showJsonButton | boolean | false | Habilita botón para exportar a JSON. | | showCsvButton | boolean | false | Habilita botón para exportar a CSV con UTF-8 BOM. | | showExcelButton | boolean | false | Habilita botón para exportar a Excel con árbol jerárquico. | | showTextFilters | boolean | false | Habilita la fila de filtros de texto para todas las columnas de forma global. | | allowRowReordering | boolean | false | Habilita el reordenamiento de filas mediante Drag & Drop. | | templates | Record<string, CustomCellRenderer> | {} | Diccionario de funciones de renderizado por nombre de plantilla. | | currencySymbol | string | '$' | Símbolo de moneda para formatear subtotales y totales. | | autoInjectStyles| boolean | true | Inyecta automáticamente los estilos CSS en el <head>. |

📋 Configuración de Columnas (SnkGridColumnDef)

| Propiedad | Tipo | Descripción | | :--- | :--- | :--- | | field | string | Nombre de la propiedad del objeto de datos. | | header | string | Título a mostrar en la cabecera. | | type | 'string' \| 'number' \| 'date' \| 'boolean' | Tipo de dato para formateo y edición. | | editable | boolean | Habilita doble clic para editar la celda. | | filterable | boolean | Habilita el filtro de selección múltiple (checklist) con buscador. | | showTextFilter | boolean | Habilita el filtro de texto para esta columna en específico. | | sortable | boolean | Habilita ordenar la columna al hacer clic en su cabecera. | | groupable | boolean | Permite arrastrar la columna a la zona de agrupación. | | defaultGroupOrder | number | Orden numérico de agrupación por defecto al iniciar (ej: 1). | | aggregate | 'sum' \| 'count' | Tipo de cálculo agregado para subtotales y total general. | | templateName | string | Nombre de la plantilla en options.templates para renderizado custom. | | cellRenderer | Function | Función directa (item, col) => HTMLElement \| string para renderizar la celda. | | width | string | Ancho de columna específico (ej: '120px', '20%'). | | custom | object | Configuración adicional como custom: { valueFormat: 'dd/MM/yyyy' }. | | children | SnkGridColumnDef[] | Columnas anidadas para cabeceras multinivel. |

📡 Métodos Públicos de la Instancia

// Actualizar datos
grid.setData(nuevosDatos);

// Obtener datos actuales
const datos = grid.getData();

// Actualizar columnas
grid.setColumns(nuevasColumnas);

// Cambiar página
grid.goToPage(2);

// Cambiar tamaño de página
grid.setPageSize(20);

// Agrupar dinámicamente
grid.setGroupBy(['departamento', 'cargo']);

// Limpiar todos los filtros
grid.clearAllFilters();

// Exportar archivos
grid.exportToExcel('reporte_empleados.xlsx');
grid.exportToCSV('reporte_empleados.csv');
grid.exportToJSON('reporte_empleados.json');

// Obtener estado completo
const state = grid.getState();

// Escuchar eventos
grid.on('cellEdit', (e) => { ... });
grid.on('rowReorder', (e) => { ... });
grid.on('pageChange', ({ page, pageSize }) => { ... });

// Destruir instancia y limpiar listeners
grid.destroy();

🎨 Personalización de Estilos con Variables CSS

Puedes sobreescribir cualquiera de las variables de diseño en tu propio CSS:

.snk-grid-container {
  --snk-primary: #4f46e5;
  --snk-primary-hover: #4338ca;
  --snk-primary-light: #eef2ff;
  --snk-border-radius: 12px;
  --snk-font-family: 'Inter', sans-serif;
}

📄 Licencia

MIT © SnakeRoads