lztic-table

[!WARNING] Paquete Obsoleto

Esta librería ha sido renombrada a lanzarote-table. Esta versión (lztic-table) ya no recibirá actualizaciones.

Por favor, migra a la nueva versión para seguir recibiendo mejoras y soporte:

npm install lanzarote-table

lztic-table es una librería de tabla de datos para Angular, potente y personalizable. Ofrece funcionalidades esenciales como paginación, ordenación, filtrado (global y por columna), exportación de datos y selección de filas, con soporte completo para renderizado tanto en cliente como en servidor.

Características Principales

• Paginación, Ordenación y Filtrado: Soporte completo para cliente y servidor.
• Selección de Filas: Selección individual y masiva con persistencia entre páginas, incluso en modo server-side.
• Exportación de Datos: Exporta los datos seleccionados (o todos) a formatos CSV, Excel y PDF.
• Personalización de Celdas: Renderiza cualquier contenido o componente en una celda usando plantillas de Angular.

Instalación

npm install lztic-table

Dependencias Adicionales

Para la funcionalidad de exportación, instala las siguientes librerías:

npm install xlsx jspdf jspdf-autotable

Guía de Inicio Rápido

1. Importa DataTableComponent en tu módulo o componente standalone.

   // tu-componente.ts
   import { DataTableComponent } from 'lztic-table';
   
   @Component({
     standalone: true,
     imports: [DataTableComponent, ...],
     // ...
   })
   export class TuComponente {}

2. Añade la tabla a tu plantilla HTML y configura los datos y columnas.

   <!-- tu-componente.html -->
   <lztic-table [data]="misDatos" [columns]="misColumnas"></lztic-table>

Configuración de Columnas

La propiedad columns es un array de objetos TableColumn, donde cada objeto define cómo se debe mostrar una columna.

Ejemplo Básico

import { TableColumn } from 'lztic-table';

// ...

columns: TableColumn[] = [
  { key: 'id', label: 'ID', type: 'string' },
  { key: 'name', label: 'Nombre', type: 'string' },
  { key: 'amount', label: 'Monto', type: 'currency' },
  { key: 'isActive', label: 'Activo', type: 'boolean' },
  { key: 'created_at', label: 'Fecha', type: 'date' },
];

Clases Condicionales en Filas (rowClassConditions)

Puedes aplicar clases CSS a las filas (<tr>) de forma condicional para resaltar datos importantes. Para ello, utiliza el input rowClassConditions.

Esta propiedad acepta un array de objetos RowClassCondition<T>, donde cada objeto tiene dos propiedades:

• condition: Una función que recibe un item de la fila (item: T) y devuelve true si la clase debe aplicarse.
• class: La cadena de texto con la(s) clase(s) CSS que se aplicarán si la condición es true.

Ejemplo

Imagina que quieres resaltar las filas donde un usuario está inactivo (activo: false) con un fondo rojo claro y aquellas donde el número de pedidos es alto (pedidos > 50) con un fondo amarillo claro.

En tu componente TypeScript:

import { Component } from '@angular/core';
import { RowClassCondition, TableColumn } from 'lztic-table'; // Asegúrate de que la ruta sea correcta

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  myData = [
    { id: 1, nombre: 'Usuario A', activo: true, pedidos: 25 },
    { id: 2, nombre: 'Usuario B', activo: false, pedidos: 60 },
    { id: 3, nombre: 'Usuario C', activo: true, pedidos: 75 },
    { id: 4, nombre: 'Usuario D', activo: false, pedidos: 10 },
  ];

  myColumns: TableColumn[] = [
    { key: 'nombre', label: 'Nombre' },
    { key: 'activo', label: 'Activo', type: 'boolean' },
    { key: 'pedidos', label: 'Pedidos' },
  ];

  // Define tus condiciones para las clases de las filas
  myRowClassConditions: RowClassCondition<any>[] = [
    {
      condition: (item) => item.activo === false,
      class: 'bg-red-50', // Clase si el item no está activo
    },
    {
      condition: (item) => item.pedidos > 50,
      class: 'bg-yellow-50', // Clase si el número es mayor que 50
    },
  ];
}

En tu plantilla HTML:

<lztic-table
  [data]="myData"
  [columns]="myColumns"
  [rowClassConditions]="myRowClassConditions"
>
</lztic-table>

Uso de badgeConfig para Celdas de Tipo badge

Para mostrar valores como etiquetas de estado (por ejemplo, "Activo", "Inactivo"), puedes usar el tipo badge. La propiedad badgeConfig te permite asignar una clase CSS y una etiqueta de texto a cada valor posible.

import { TableColumn } from 'lztic-table';

// ...

users = [
  { id: 1, name: 'Usuario A', status: 'active' },
  { id: 2, name: 'Usuario B', status: 'inactive' },
  { id: 3, name: 'Usuario C', status: 'pending' },
];

columns: TableColumn[] = [
  { key: 'id', label: 'ID' },
  { key: 'name', label: 'Nombre' },
  {
    key: 'status',
    label: 'Estado',
    type: 'badge', // Define el tipo de columna como 'badge'
    badgeConfig: {
      'active': { 
        class: 'bg-green-200 text-green-800', // Clase CSS para el estilo
        label: 'Activo'                        // Texto a mostrar
      },
      'inactive': { 
        class: 'bg-red-200 text-red-800', 
        label: 'Inactivo' 
      },
      'pending': { 
        class: 'bg-yellow-200 text-yellow-800', 
        label: 'Pendiente' 
      }
    }
  }
];

El resultado será una columna "Estado" que muestra badges estilizados según el valor de status de cada fila.

Personalización de Celdas con tableCellTemplate

Puedes personalizar completamente el contenido de cualquier celda, sin importar su type, utilizando la directiva tableCellTemplate.

1. Importa DataTableComponent y CellTemplateDirective en tu componente standalone.

   // tu-componente.ts
   import { DataTableComponent, CellTemplateDirective } from 'lztic-table';
   
   @Component({
     standalone: true,
     imports: [DataTableComponent, CellTemplateDirective, /* ... otros módulos como CommonModule */],
     // ...
   })
   export class TuComponente {}

2. Identifica la columna que quieres personalizar en tu array de columns. El type puede ser 'string', 'badge', etc.

   // tu-componente.ts
   misColumnas: TableColumn[] = [
     { key: 'nombre', label: 'Nombre', type: 'string' },
     { key: 'estado', label: 'Estado', type: 'badge', badgeConfig: { /* ... */ } },
     { key: 'acciones', label: 'Acciones', type: 'string' } // No necesita ser 'template'
   ];

3. En tu plantilla HTML, añade un <ng-template> dentro de la tabla. Usa la directiva tableCellTemplate y pásale como valor el key de la columna que quieres sobreescribir.

   <!-- tu-componente.html -->
   <lztic-table [data]="misDatos" [columns]="misColumnas">
   
     <!-- Ejemplo 1: Transformar el texto de la columna 'nombre' -->
     <ng-template tableCellTemplate="nombre" let-item>
       <strong>{{ item.nombre | uppercase }}</strong>
     </ng-template>
   
     <!-- Ejemplo 2: Añadir botones a la columna 'acciones' -->
     <ng-template tableCellTemplate="acciones" let-item>
       <button (click)="editar(item)">Editar</button>
     </ng-template>
   
   </lztic-table>

Añadir Botones Personalizados en la Cabecera

Puedes añadir tus propios botones y componentes en la cabecera de la tabla, junto al botón "NUEVO", utilizando la proyección de contenido de Angular.

Para ello, añade un contenedor con el atributo lztic-header-actions dentro de la etiqueta <lztic-table>. Todo el contenido dentro de este contenedor se proyectará en la cabecera.

Ejemplo:

<!-- tu-componente.html -->
<lztic-table
  [data]="misDatos"
  [columns]="misColumnas"
  [showNewButton]="true"
>
  <!-- Contenedor para los botones personalizados -->
  <div lztic-header-actions>
    <button class="dt-button" (click)="miAccionPersonalizada()">
      <span>Acción Personalizada</span>
    </button>
  </div>

</lztic-table>

Consejo: Para mantener un estilo consistente, puedes usar la clase dt-button en tus botones, tal como se muestra en el ejemplo.

Proyectar Contenido en el Título

En lugar de una simple cadena de texto, puedes inyectar cualquier contenido HTML o componente de Angular en el área del título de la tabla. Esto te da la flexibilidad de añadir subtítulos, badges, o cualquier otro elemento interactivo.

Para ello, utiliza un contenedor con el atributo lztic-title-content.

Ejemplo:

<!-- tu-componente.html -->
<lztic-table [data]="misDatos" [columns]="misColumnas">

  <!-- Contenido personalizado para el título -->
  <div lztic-title-content>
    <h2>Ventas del Mes</h2>
    <span class="subtitulo">Reporte actualizado al día de hoy</span>
  </div>

</lztic-table>

3. Define los datos y la estructura de las columnas en tu componente.

   // tu-componente.ts
   import { Column } from 'lztic-table';
   
   // ...
   export class TuComponente {
     misDatos = [
       { id: 1, nombre: 'Producto A', categoria: 'Electrónica', precio: 199.99 },
       { id: 2, nombre: 'Producto B', categoria: 'Libros', precio: 24.99 },
     ];
   
     misColumnas: Column[] = [
       { key: 'id', label: 'ID' },
       { key: 'nombre', label: 'Nombre del Producto' },
       { key: 'categoria', label: 'Categoría' },
       { key: 'precio', label: 'Precio', type: 'currency' }, // El tipo 'currency' formatea el número como moneda
     ];
   }

Configuración Global (Opcional)

lztic-table permite establecer una configuración por defecto para todas las instancias de la tabla a nivel de aplicación. Esto es útil para mantener un estilo y comportamiento consistentes sin tener que declarar las mismas propiedades de entrada (@Input) una y otra vez.

Esto se logra proveyendo un objeto de configuración a través del InjectionToken LZTIC_TABLE_OPTIONS.

Opciones Configurables

export interface LzticTableOptions {
  density?: 'compact' | 'normal' | 'spacious';
  pagination?: boolean;
  pageSizeOptions?: number[];
  pageSize?: number;
  striped?: boolean;
  globalSearch?: boolean;
  showColumnFilters?: boolean;
  showExportButtons?: boolean;
  showSelection?: boolean;
  showNewButton?: boolean;
  showHideColumns?: boolean;
}

Ejemplo de Uso en una Aplicación Standalone

En tu fichero app.config.ts, añade la configuración al array de providers:

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { LZTIC_TABLE_OPTIONS } from 'lztic-table';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: LZTIC_TABLE_OPTIONS,
      useValue: {
        density: 'compact',
        pagination: true,
        pageSize: 50,
        showExportButtons: true,
      },
    },
  ],
};

Ejemplo de Uso en una Aplicación con NgModules

En tu fichero app.module.ts:

// app.module.ts
import { NgModule } from '@angular/core';
import { LZTIC_TABLE_OPTIONS } from 'lztic-table';

@NgModule({
  //...
  providers: [
    {
      provide: LZTIC_TABLE_OPTIONS,
      useValue: {
        density: 'compact',
        pagination: true,
        pageSize: 50,
      },
    },
  ],
})
export class AppModule {}

Con esta configuración, cualquier tabla que no especifique estas propiedades directamente usará los valores globales. Cualquier propiedad definida en la plantilla del componente (<lztic-table [pagination]="false">) tendrá prioridad sobre la configuración global.

API y Opciones de Configuración

Propiedades de Entrada (@Input)

data: T[]

El array de objetos que se mostrarán en la tabla. T puede ser cualquier tipo de objeto.

columns: Column[]

Define la estructura de las columnas. La interfaz Column tiene las siguientes propiedades:

• key: string: La clave del objeto de datos a mostrar en la celda.
• label: string: El texto que se mostrará en la cabecera de la columna.
• type?: 'string' | 'numeric' | 'currency' | 'date' | 'badge' | 'boolean' | 'select' | 'datetime': (Opcional) El tipo de dato para aplicar un formato predefinido. Por defecto es 'string'.
• sortable?: boolean: (Opcional) Permite que la columna sea ordenable. Por defecto es true.
• filterable?: boolean: (Opcional) Habilita un filtro específico para esta columna. Por defecto es true.

density: 'normal' | 'compact' | 'spacious'

• Valor: 'normal' (por defecto), 'compact', o 'spacious'.
• Uso: Ajusta la densidad visual de la tabla. Puede ser preconfigurado globalmente.

pagination: boolean

• Valor: true o false (por defecto false).
• Uso: Muestra u oculta el paginador. Puede ser preconfigurado globalmente.

pageSize: number

• Valor: Un número (por defecto 25).
• Uso: Define cuántas filas se muestran por página. Puede ser preconfigurado globalmente.

pageSizeOptions: number[]

• Valor: Un array de números (por defecto [25, 50, 100]).
• Uso: Define las opciones disponibles en el selector de tamaño de página. Puede ser preconfigurado globalmente.

serverSide: boolean

• Valor: true o false (por defecto false).
• Uso: Activa el modo server-side. En este modo, la tabla emite un evento stateChanged para que el servidor procese los datos.

totalItems: number

• Uso: Requerido en modo serverSide. Indica el número total de registros para calcular la paginación. Por defecto es 0.

loading: boolean

• Valor: true o false (por defecto false).
• Uso: Muestra una superposición de carga, ideal para operaciones asíncronas.

striped: boolean

• Valor: true o false (por defecto true).
• Uso: Aplica un estilo de filas alternas (cebreado). Puede ser preconfigurado globalmente.

globalSearch: boolean

• Valor: true o false (por defecto false).
• Uso: Muestra un campo de búsqueda global. Puede ser preconfigurado globalmente.

showColumnFilters: boolean

• Valor: true o false (por defecto true).
• Uso: Muestra u oculta la fila de filtros por columna. Puede ser preconfigurado globalmente.

showExportButtons: boolean

• Valor: true o false (por defecto false).
• Uso: Muestra los botones para exportar los datos. Puede ser preconfigurado globalmente.

showSelection: boolean

• Valor: true o false (por defecto false).
• Uso: Muestra una columna de checkboxes para la selección de filas. Puede ser preconfigurado globalmente.

showNewButton: boolean

• Valor: true o false (por defecto false).
• Uso: Muestra un botón "Nuevo" en la cabecera. Emite el evento newButtonClicked. Puede ser preconfigurado globalmente.

showHideColumns: boolean

• Valor: true o false (por defecto false).
• Uso: Muestra un menú para ocultar/mostrar columnas. Puede ser preconfigurado globalmente.

dataKey: string

• Uso: Requerido para la persistencia de selección en modo serverSide. Es el nombre de la propiedad que actúa como identificador único para cada fila (ej: 'id').

rowClassConditions: RowClassCondition<T>[]

• Valor: Un array de objetos RowClassCondition<T>. Por defecto es [].
• Uso: Permite aplicar clases CSS a las filas (<tr>) de forma condicional. Cada objeto en el array define una condition (una función que devuelve un booleano) y una class (la clase CSS a aplicar si la condición es verdadera).

Eventos de Salida (@Output)

stateChanged: EventEmitter<TableState>

• Se emite: Solo en modo serverSide, cuando el usuario cambia de página, ordena una columna o aplica un filtro.
• Payload (TableState): Un objeto que contiene el estado actual de la tabla para que puedas construir la consulta al backend.

  export interface TableState {
    skip: number;       // Número de registros a saltar (offset)
    first: number;      // Número de registros a tomar (limit)
    order?: string | null; // Columna de ordenación ('-columna' para descendente)
    search?: string | null;  // Valor del filtro global
    filtros?: TableFilter[] | null; // Array de filtros por columna
  }

Uso Avanzado

Personalización de Celdas

Usa la directiva *lzticCellTemplate para tomar el control total sobre el renderizado de una celda.

• Variables de Plantilla: let-row (el objeto completo de la fila) y let-value (el valor de la celda).
• columnKey: Asocia la plantilla con una columna específica.

<lztic-table [data]="usuarios" [columns]="columnasUsuarios">

  <!-- Ejemplo 1: Renderizar una celda con botones de acción -->
  <ng-template lzticCellTemplate let-row="row" columnKey="acciones">
    <button (click)="editar(row.id)">Editar</button>
    <button (click)="eliminar(row.id)">Eliminar</button>
  </ng-template>

  <!-- Ejemplo 2: Aplicar un formato o un componente personalizado -->
  <ng-template lzticCellTemplate let-value="value" columnKey="estado">
    <span class="status-badge" [ngClass]="'status-' + value">{{ value }}</span>
  </ng-template>

</lztic-table>