NgTablePg

Un componente de tabla potente y flexible para aplicaciones Angular con funciones integradas de ordenamiento, filtrado, paginación y arrastrar y soltar.

Autor

• Nombre: Alejandro Pérez Granado
• Redes sociales: alejoperez.dev
• GitHub: @alejandr0pg

Características

• ✨ Diseño responsive con estilos CSS compilados (sin dependencia de Tailwind)
• 🔍 Funcionalidad de búsqueda
• 🔄 Ordenamiento de columnas
• 📊 Filtros personalizados
• 📱 Paginación
• 📎 Reordenamiento de filas con arrastrar y soltar
• 📥 Exportación a CSV y Excel
• 🎨 Estilos auto-contenidos (no requiere Tailwind CSS en el proyecto consumidor)
• 🌐 Soporte para internacionalización
• 💫 Estado de carga con skeleton loader
• 🛠️ Botones de acción personalizados
• 📋 Plantillas de columnas personalizadas
• ✅ Responsive Design: Adaptación automática a diferentes tamaños de pantalla
• ✅ Scroll Horizontal Mejorado: Con indicadores visuales y scroll suave
• ✅ Prioridades de Columnas: Control granular de qué columnas mostrar en cada dispositivo
• ✅ Drag & Drop: Reordenamiento de filas con soporte cross-page
• ✅ Paginación Avanzada: Con drag & drop entre páginas
• ✅ Filtros: Sistema de filtros flexible y personalizable
• ✅ Búsqueda: Búsqueda global en tiempo real
• ✅ Exportación: CSV y Excel con traducciones
• ✅ Skeleton Loading: Estados de carga elegantes
• ✅ Internacionalización: Soporte completo para i18n
• ✅ TypeScript: Completamente tipado

Instalación

1npm install ng-table-pg

Dependencias

Instala las dependencias requeridas:

1npm install @angular/cdk file-saver xlsx @ngx-translate/core

⚠️ Importante: Estilos CSS

A partir de la versión 0.0.10, la librería incluye todos los estilos CSS compilados internamente.

• ✅ NO necesitas instalar Tailwind CSS en tu proyecto
• ✅ NO necesitas configurar Tailwind CSS
• ✅ Los estilos se incluyen automáticamente con el componente

Migración desde versiones anteriores

Si estabas usando una versión anterior que requería Tailwind CSS:

1. Puedes remover Tailwind CSS de tu proyecto si solo lo usabas para ng-table-pg
2. Los estilos seguirán funcionando exactamente igual
3. No necesitas cambiar nada en tu código

Configuración de Desarrollo

Servidor de desarrollo

Inicia el servidor de desarrollo:

1ng serve

Navega a http://localhost:4200/. La aplicación se recargará automáticamente si cambias alguno de los archivos fuente.

Compilación de la Librería

Compila la librería:

1ng build table-lib

Los archivos compilados se almacenarán en el directorio dist/.

Ejecutar Pruebas

Ejecuta las pruebas unitarias vía Karma:

1ng test table-lib

Guía de Uso

Implementación Básica

1. Importa el componente en tu módulo:

1import { TableComponent } from 'ng-table-pg';
2
3@NgModule({
4  imports: [
5    TableComponent
6  ]
7})

2. Úsalo en tu componente:

1import { Component } from '@angular/core';
2
3@Component({
4  template: `
5    <ng-table-pg
6      [data]="items"
7      [columns]="columns"
8      [loading]="loading"
9    ></ng-table-pg>
10  `
11})
12export class YourComponent {
13  items = [...];
14  columns = [
15    { key: 'id', label: 'ID' },
16    { key: 'name', label: 'Nombre' },
17    { key: 'email', label: 'Correo' }
18  ];
19}

Opciones de Configuración

Configuración de Columnas

1interface ITableColumns {
2  key: string; // Clave de la propiedad del objeto de datos
3  label: string; // Etiqueta del encabezado de la columna
4  width?: string | number; // Ancho de la columna
5  type?: "date" | "date-time" | "currency" | "boolean" | "status" | "state";
6  transform?: (value: any, item: any) => any; // Transformador de valor personalizado
7}

Botones de Acción

1interface ITableActions {
2  label: string; // Etiqueta del botón
3  handler: (item: any) => void; // Manejador del clic
4  show?: (item: any) => boolean; // Visualización condicional
5}

Internacionalización

Estructura requerida para las traducciones:

1{
2  "TABLE": {
3    "SEARCH": "Buscar...",
4    "FILTERS": "Filtros",
5    "SHOWING": "Mostrando",
6    "OF": "de",
7    "RESULTS": "resultados",
8    "EXPORT_CSV": "Exportar CSV",
9    "EXPORT_EXCEL": "Exportar Excel",
10    "ACTIONS": "Acciones"
11  }
12}

Arquitectura de Estilos

Estilos Auto-Contenidos

La librería utiliza un enfoque de estilos auto-contenidos:

• CSS Compilado: Todos los estilos de Tailwind necesarios están pre-compilados
• Sin Dependencias: No requiere Tailwind CSS en el proyecto consumidor
• Optimizado: Solo incluye las clases CSS que realmente se usan
• Compatible: Funciona con cualquier framework CSS (Bootstrap, Material, etc.)

Personalización de Estilos

Si necesitas personalizar los estilos:

1// En tu archivo de estilos globales
2ng-table-pg {
3  // Sobrescribe estilos específicos
4  .custom-table-header {
5    background-color: your-color;
6  }
7
8  // Usa !important si es necesario para sobrescribir
9  .custom-button {
10    background-color: your-color !important;
11  }
12}

Changelog

v0.0.10

• ✨ Estilos auto-contenidos: Eliminada la dependencia de Tailwind CSS
• 🔧 Mejor compatibilidad: Funciona con cualquier proyecto Angular
• 📦 Tamaño optimizado: Solo incluye CSS necesario
• 🐛 Correcciones: Skeleton loader mejorado

Versiones anteriores

• Requerían Tailwind CSS en el proyecto consumidor
• Dependencias externas para estilos

Contribuir

1. Haz un fork del repositorio
2. Crea tu rama de características (git checkout -b feature/CaracteristicaIncreible)
3. Haz commit de tus cambios (git commit -m 'Añadir alguna CaracteristicaIncreible')
4. Haz push a la rama (git push origin feature/CaracteristicaIncreible)
5. Abre un Pull Request

Licencia

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

Soporte

Para soporte, por favor abre un issue en el repositorio de GitHub o contacta directamente al autor.

Recursos Adicionales

• Documentación de Angular
• Documentación de Angular CLI
• Documentación de Angular CDK

---

¡Gracias por usar ng-table-pg! 🚀

Uso Básico

1import { TableComponent } from "ng-table-pg";
2
3@Component({
4  selector: "app-example",
5  standalone: true,
6  imports: [TableComponent],
7  template: ` <ng-table-pg [data]="data" [columns]="columns" [actions]="actions" [loading]="loading" [responsive]="true" [compactMode]="false" [stickyHeader]="true" [showScrollIndicators]="true" [minTableWidth]="'800px'" [horizontalScroll]="true"></ng-table-pg> `,
8})
9export class ExampleComponent {
10  data = [
11    { id: 1, name: "John Doe", email: "john@example.com", status: true },
12    // ... más datos
13  ];
14
15  columns: ITableColumns[] = [
16    {
17      key: "id",
18      label: "ID",
19      width: 80,
20      priority: 1, // Siempre visible
21      sortable: true,
22    },
23    {
24      key: "name",
25      label: "Nombre",
26      priority: 1, // Siempre visible
27      expandable: true, // Permite expansión del contenido
28      sortable: true,
29      minWidth: 150,
30    },
31    {
32      key: "email",
33      label: "Email",
34      priority: 2, // Ocultar en móvil
35      sortable: true,
36      minWidth: 200,
37    },
38    {
39      key: "status",
40      label: "Estado",
41      type: "status",
42      priority: 1, // Siempre visible
43      sortable: true,
44      width: 100,
45    },
46  ];
47
48  actions: ITableActions[] = [
49    {
50      label: "Editar",
51      handler: (item) => this.edit(item),
52      show: (item) => item.canEdit,
53    },
54    {
55      label: "Eliminar",
56      handler: (item) => this.delete(item),
57    },
58  ];
59}

Propiedades de Configuración

Propiedades Principales

Propiedad	Tipo	Defecto	Descripción
data	any[]	[]	Datos a mostrar en la tabla
columns	ITableColumns[]	[]	Configuración de columnas
actions	ITableActions[]	[]	Acciones por fila
loading	boolean	false	Estado de carga

Propiedades Responsive

Propiedad	Tipo	Defecto	Descripción
responsive	boolean	true	Habilita el modo responsive
stickyHeader	boolean	false	Header fijo al hacer scroll
compactMode	boolean	false	Modo compacto para pantallas pequeñas
horizontalScroll	boolean	true	Permite scroll horizontal
minTableWidth	string	'800px'	Ancho mínimo de la tabla
maxTableHeight	string	'none'	Altura máxima con scroll vertical
showScrollIndicators	boolean	true	Muestra indicadores de scroll
alwaysShowScrollbar	boolean	false	Fuerza la visibilidad del scrollbar
scrollbarStyle	string	'default'	Estilo del scrollbar horizontal
hideColumnsOnResize	boolean	false	Si true oculta columnas, si false usa scroll

Configuración de Columnas

1interface ITableColumns {
2  key: string; // Clave del dato
3  label: string; // Etiqueta de la columna
4  type?: string; // Tipo de dato (status, date, currency, etc.)
5  transform?: (value: any, row: any) => any; // Función de transformación
6  width?: number | string; // Ancho de la columna
7
8  // Nuevas propiedades responsive
9  priority?: 1 | 2 | 3; // Prioridad de visualización
10  expandable?: boolean; // Permite expansión del contenido
11  sortable?: boolean; // Columna ordenable
12  resizable?: boolean; // Columna redimensionable
13  minWidth?: number | string; // Ancho mínimo
14  maxWidth?: number | string; // Ancho máximo
15}

Prioridades de Columnas

• Priority 1: Siempre visible (columnas esenciales)
• Priority 2: Oculta en tablet y móvil (< 768px)
• Priority 3: Oculta en móvil (< 640px)

Ejemplos de Uso

Tabla Responsive Básica

1columns: ITableColumns[] = [
2  {
3    key: 'id',
4    label: 'ID',
5    width: 60,
6    priority: 1
7  },
8  {
9    key: 'name',
10    label: 'Nombre',
11    priority: 1,
12    expandable: true,
13    minWidth: 150
14  },
15  {
16    key: 'email',
17    label: 'Email',
18    priority: 2, // Se oculta en móvil
19    minWidth: 200
20  },
21  {
22    key: 'phone',
23    label: 'Teléfono',
24    priority: 3, // Se oculta en tablet y móvil
25    minWidth: 120
26  }
27];

Tabla con Scroll Horizontal Controlado

1<ng-table-pg 
2  [data]="data" 
3  [columns]="columns" 
4  [responsive]="true" 
5  [horizontalScroll]="true" 
6  [showScrollIndicators]="true" 
7  [minTableWidth]="'1200px'" 
8  [maxTableHeight]="'400px'">
9</ng-table-pg>

Tabla con Scrollbar Personalizado

1<!-- Scrollbar siempre visible -->
2<ng-table-pg 
3  [data]="data" 
4  [columns]="columns" 
5  [alwaysShowScrollbar]="true">
6</ng-table-pg>
7
8<!-- Scrollbar prominente -->
9<ng-table-pg 
10  [data]="data" 
11  [columns]="columns" 
12  [scrollbarStyle]="'prominent'">
13</ng-table-pg>
14
15<!-- Scrollbar mínimo -->
16<ng-table-pg 
17  [data]="data" 
18  [columns]="columns" 
19  [scrollbarStyle]="'minimal'">
20</ng-table-pg>

Estilos de Scrollbar

• default: Scrollbar estándar con diseño coherente (14px, gris)
• prominent: Scrollbar más grande y colorido (18px, azul índigo)
• minimal: Scrollbar discreto y pequeño (8px, semi-transparente)

Tabla con Comportamiento Responsive Personalizado

1<!-- Modo scroll horizontal (recomendado) - mantiene diseño intacto -->
2<ng-table-pg 
3  [data]="data" 
4  [columns]="columns" 
5  [responsive]="true"
6  [hideColumnsOnResize]="false">
7</ng-table-pg>
8
9<!-- Modo ocultar columnas - para casos específicos -->
10<ng-table-pg 
11  [data]="data" 
12  [columns]="columns" 
13  [responsive]="true"
14  [hideColumnsOnResize]="true">
15</ng-table-pg>

Comportamientos Responsive

• hideColumnsOnResize: false (default): Mantiene todas las columnas visibles con scroll horizontal
• hideColumnsOnResize: true: Oculta columnas según prioridad en pantallas pequeñas

Tabla Compacta para Móviles

1<ng-table-pg [data]="data" [columns]="columns" [compactMode]="true" [stickyHeader]="true" [itemsPerPage]="5"></ng-table-pg>

Tipos de Datos Soportados

La tabla soporta diferentes tipos de datos con formateo automático:

• status: Estados con badges de colores
• date: Fechas formateadas
• date-time: Fecha y hora
• currency: Moneda con formato
• boolean: Sí/No
• json: JSON formateado
• html: HTML renderizado
• wallet: Direcciones de wallet truncadas

Responsive Breakpoints

1// Móvil
2@media (max-width: 640px) {
3  .col-priority-2,
4  .col-priority-3 {
5    display: none;
6  }
7}
8
9// Tablet
10@media (max-width: 768px) {
11  .col-priority-3 {
12    display: none;
13  }
14}

Personalización de Estilos

1// Personalizar scroll indicators
2ng-table-pg .scroll-indicator {
3  background: linear-gradient(to right, rgba(0, 0, 0, 0.1), transparent);
4}
5
6// Personalizar tabla compacta
7ng-table-pg .responsive-table.compact {
8  font-size: 0.8rem;
9}
10
11// Personalizar header sticky
12ng-table-pg .sticky-header {
13  background: rgba(255, 255, 255, 0.95);
14  backdrop-filter: blur(10px);
15}

Migración desde Versiones Anteriores

Cambios en v2.0

1. Nuevas propiedades de columna: priority, expandable, sortable, etc.
2. Propiedades responsive: Control granular de responsividad
3. Scroll indicators: Indicadores visuales de scroll
4. Mejoras de rendimiento: Optimizaciones en el scroll horizontal

Actualizar Configuración Existente

1// Antes (v1.x)
2columns = [{ key: "name", label: "Nombre", width: 200 }];
3
4// Después (v2.x)
5columns = [
6  {
7    key: "name",
8    label: "Nombre",
9    width: 200,
10    priority: 1, // Nueva
11    expandable: true, // Nueva
12    sortable: true, // Nueva
13  },
14];

Contribuir

1. Fork el repositorio
2. Crea una rama para tu feature
3. Commit tus cambios
4. Push a la rama
5. Abre un Pull Request

Licencia

MIT License